Bug 9843

Summary:	Suggested additions to the documentation on PR
Product:	[Documentation] Reference	Reporter:	ulfalizer
Component:	handbook	Assignee:	Scott Rifenbark <srifenbark>
Status:	RESOLVED FIXED	QA Contact:
Severity:	enhancement
Priority:	Medium	CC:	bluelightning, poky.doc.watcher, poky.watcher, sgw, srifenbark
Version:	2.3
Target Milestone:	2.2 M2
Hardware:	x86
OS:	Multiple
Whiteboard:	30 June 2016: RESOLVED
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Done (doc changes complete)

Description ulfalizer 2016-06-28 20:22:21 UTC

I've seen a lot of confusion related to the purpose of PR. I suggest extending the glossary entry as follows:


PR

The revision of the recipe. The default value for this variable is "r0", with subsequent revisions conventionally having the values "r1", "r2", etc. When PV is increased, PR should conventionally be reset to "r0".

[Note]

Yocto does not need the aid of PR to know when a recipe needs to be rebuilt. This is done automatically via the (STAMP)[http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-STAMP) and (shared state cache)[http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#shared-state-cache] mechanisms.

PR mostly becomes significant when packages are dynamically installed (by running a package manager) on an already built image. In this case, PR (by being the default value of (PKGR)[http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-PKGR]) helps the package manager distinguish which package is the most recent one in cases where many packages have the same PV (PKGV). This usually happens when the packages install the same upstream version, but some of them include packaging fixes. Note that PR does not need to be increased for changes that do not change the package contents or metadata.

Since manually managing PR can be cumbersome and error-prone, an automated solution is available. See (Working With a PR Service)[http://www.yoctoproject.org/docs/1.6.1/dev-manual/dev-manual.html#working-with-a-pr-service].

Comment 1 Scott Rifenbark 2016-06-29 15:32:39 UTC

Hi, 

See the http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-PR description for PR with the changes.  I did standard re-writing for a more active voice.  Let me know if my changes altered technical meaning. 

Thanks,
Scott

Comment 2 ulfalizer 2016-06-29 23:48:53 UTC

(In reply to comment #1)
> Hi, 
> 
> See the
> http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-PR
> description for PR with the changes.  I did standard re-writing for a more
> active voice.  Let me know if my changes altered technical meaning. 
> 
> Thanks,
> Scott

This sounds a bit weird:

"Packages have the same PV usually when the package manager installs the same upstream version and some of the packages include packaging fixes."

I'd rewrite it as 

"A component having many packages with the same PV usually means that the packages all install the same upstream version, but with later (PR) version packages including packaging fixes."


There's an extra comma after "because" in

"Because, manually managing PR can be cumbersome and error-prone, an automated solution exists. See the "Working With a PR Service" section for more information."

Comment 3 Scott Rifenbark 2016-06-30 20:03:38 UTC

Got it... see http://www.yoctoproject.org/docs/2.2/ref-manual/ref-manual.html#var-PR.

Anything further on this?

Thanks, 
Scott

Comment 4 ulfalizer 2016-06-30 20:24:49 UTC

Looks fine to me now. Thanks!

Comment 5 Scott Rifenbark 2016-06-30 20:26:12 UTC

Thanks!

I am setting to RESOLVED and putting the doc flag to "done."

Scott