Bug 8079

Summary:	Improve migration guide
Product:	[Documentation] Reference	Reporter:	Joshua Lock <joshuagloe>
Component:	handbook	Assignee:	Scott Rifenbark <srifenbark>
Status:	VERIFIED FIXED	QA Contact:	Bogdan Alexandru Voiculescu <bogdanx.a.voiculescu>
Severity:	enhancement
Priority:	Medium	CC:	bluelightning, bogdanx.a.voiculescu, poky.doc.watcher, poky.watcher, srifenbark
Version:	unspecified
Target Milestone:	2.1
Hardware:	x86
OS:	Multiple
Whiteboard:	18 Jan 2016: RESOLVED
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Done (doc changes complete)

Description Joshua Lock 2015-07-30 12:22:35 UTC

The migration notes are extremely helpful when updating to a newer version of the core metadata, however I've observed several people watch their layers explode and not know where to start.

A big cause of that in recent releases is that the gcc compiler suite has been getting increasingly strict with each release and it would be extremely useful to help migrators adopt the newer gcc with less pain.

For example the stricter checks often result in updates to various recipes during development and these could be linked from the migration guide to give an example of the changes in the compiler and potential approaches to addressing those changes.

At the very least it would be helpful to users to point to the GCC "migrating to" guides i.e. https://gcc.gnu.org/gcc-5/porting_to.html

A more general solution might be to provide links to upstream changelogs, when provided, with a "highlights" section pointing out those changes most likely to cause issues when migrating from a previous release.

Comment 1 Scott Rifenbark 2015-09-16 18:23:20 UTC

Hi Joshua, 

Good points on the section for migration.  I am adding Paul Eggleton to the bug CC list as Paul in the past has drafted the migration section.  Hopefully we can get some of these improvements in as a standard for that section when going to a new release.

Scott

Comment 2 Scott Rifenbark 2015-09-22 15:04:20 UTC

Assuming I have information, I can get the desired enhancements into this part of the ref-manual in a day.

Scott

Comment 3 Paul Eggleton 2015-11-02 15:41:38 UTC

We missed the porting guide out of the migration info - my apologies; I've asked Scott to add that. We probably should have linked to some more examples, but I think we may be out of time.

Regarding linking to upstream changelogs, that's a great idea and one I've thought about myself; the challenge would be coping with all of the different ways upstream projects provide some of that information; unfortunately not all of it is web-accessible (e.g. it's only provided in a file inside the release tarball). We'd probably need to add some metadata to each recipe and then have a script that would collect it all together in an HTML document, or at least HTMLise the ones that don't provide the information in web-accessible form so they can be uploaded and then linked to.

Comment 4 Scott Rifenbark 2016-01-07 19:43:35 UTC

Looking back on this bug (going deep through my in-box) and I see that we did get a reference to the porting guide in the migration section of the ref-manual (http://www.yoctoproject.org/docs/2.0/ref-manual/ref-manual.html#migration-2.0-gcc-5).

For this bug, do we call it good for the docs?  Or, do we keep it open in hopes of doing some of the things mentioned in Joshua's initial post and Paul's Comment 3?

Thanks, 
Scott

Comment 5 Joshua Lock 2016-01-15 15:41:56 UTC

(In reply to comment #4)
> Looking back on this bug (going deep through my in-box) and I see that we
> did get a reference to the porting guide in the migration section of the
> ref-manual
> (http://www.yoctoproject.org/docs/2.0/ref-manual/ref-manual.html#migration-2.
> 0-gcc-5).
> 
> For this bug, do we call it good for the docs?  Or, do we keep it open in
> hopes of doing some of the things mentioned in Joshua's initial post and
> Paul's Comment 3?

I'm OK with resolving this bug.

Comment 6 Scott Rifenbark 2016-01-18 18:10:38 UTC

Marking RESOLVED and setting the doc flag to "done".

Scott

Comment 7 Bogdan Alexandru Voiculescu 2016-03-14 10:00:58 UTC

Verified