Bug 11731

Summary:	Docs: poky and meta-intel branch names in quick start guide represent a moving target
Product:	[Documentation] General Docs	Reporter:	Henry Bruce <henry.bruce>
Component:	docs-general	Assignee:	Saul Wold <sgw>
Status:	RESOLVED FIXED	QA Contact:
Severity:	enhancement
Priority:	Medium	CC:	brian.avery, kristi, srifenbark
Version:	unspecified
Target Milestone:	2.4 M4
Hardware:	x86
OS:	Multiple
Whiteboard:	07 Sept 2017: RESOLVED
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Done (doc changes complete)

Description Henry Bruce 2017-06-28 20:19:55 UTC

For developers new to Yocto Project the Quick Start Guide is often the first place they pick up guidance on how to develop. The guide refers the release branches and developers are usually unaware that these refer to meta-data data this is changing over time. 

Imagine two developers Fred and Tim. Fred does a build on a given date and Tim who pulls and builds the meta-data 2 weeks later will likely have a different built. 

We should explain the Quick Start Guide always points to the best (i.e. bug fixed and CVE applied) meta-data while release tags should be used to keep on a known good build. We should also explain that although release branches have consistent naming across poky, meta-oe, meta-intel (and maybe others?), tags do not.

Comment 1 Kristi 2017-06-28 21:49:24 UTC

Henry, 

I'm taking this bug, and yes, I see what you mean. I will change those two examples so they're checking out on a tag to give them a known spot on the branch and alleviating the "moving target" issue. 

Kristi

Comment 2 brian avery 2017-06-29 15:14:13 UTC

while it may not belong in the quick start guide, I believe the main documentation needs a chapter on branches and tags explaining how both work and what the intent of each is.

Comment 3 Kristi 2017-06-29 23:10:06 UTC

Henry - I've updated the relevant sections to use tag checkouts:

http://www.yoctoproject.org/docs/temp/yocto-project-qs/yocto-project-qs.html#releases

http://www.yoctoproject.org/docs/temp/yocto-project-qs/yocto-project-qs.html#building-an-image-for-hardware

Regarding Comment 2, Scott has addressed that in the following dev-manual sections:

http://www.yoctoproject.org/docs/2.4/dev-manual/dev-manual.html#checking-out-by-branch-in-poky

http://www.yoctoproject.org/docs/2.4/dev-manual/dev-manual.html#checkout-out-by-tag-in-poky

Please look this stuff over, and if there are any issues let me know. 

Thanks
Kristi

Comment 4 Scott Rifenbark 2017-09-07 20:22:27 UTC

No feedback in over a month.  Presumed correct.  Setting to RESOLVED and putting the doc flag to "done."

Scott