Best Known Methods (BKMs) for Package Updating - Revision history

RossBurton: /* Patch Upstreaming */

2025-03-12T15:35:17Z

Patch Upstreaming

@@ Line 44: / Line 44: @@
 In order to keep track of patches and ultimate reduce the number of patches that the Yocto Project maintains, we need to track the status of the patches that are created. As mentioned above, the patches should contain comments about why they are created, by whom and when, we also want to track if it's appropriate to get this particular patch into the upstream project. Since we want to track this information, we need a consistent tag and set of status that can be searched. Be sure to include any URL to bug tracking, mailing list or other reference material pertaining to the patch.
-'''Upstream-Status:'''
+The complete list of patch status fields can be found in the [https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html#patch-upstream-status Recipe Style Guide] documentation.
 All patches and diff files should include this information.

PaulEggleton: /* Distro Tracking Fields */

2014-06-10T13:16:12Z

Distro Tracking Fields

← Older revision		Revision as of 13:16, 10 June 2014
Line 81:		Line 81:
	;RECIPE_COLOR		;RECIPE_COLOR
	: Indicates whether the recipe has been reviewed for basic quality control information (e.g, has had its software license verified). "red" indicates these checks have not been done, and "green" indicates that they have been done.		: Indicates whether the recipe has been reviewed for basic quality control information (e.g, has had its software license verified). "red" indicates these checks have not been done, and "green" indicates that they have been done.
	;~~RECIPE_UPSTREAM_DATE~~		;RECIPE_UPSTREAM_VERSION
	: The latest upstream stable version		: The latest upstream stable version
	;RECIPE_UPSTREAM_DATE		;RECIPE_UPSTREAM_DATE

PaulEggleton: Remove/replace old, outdated or duplicated information

2014-06-05T13:43:21Z

Remove/replace old, outdated or duplicated information

Show changes

PaulEggleton: Grammar and other minor corrections

2012-07-24T11:15:17Z

Grammar and other minor corrections

← Older revision		Revision as of 11:15, 24 July 2012
Line 1:		Line 1:
	This page is used for capturing the Best Known Methods (BKMs) of package upgrading as we ~~get reviewed~~ and process more of the packages.		This page is used for capturing the Best Known Methods (BKMs) for package upgrading as we review and process more of the packages.

	== Don't retain older versions ==		== Don't retain older versions ==
Line 13:		Line 13:
	This is a good visual reminder to bump in the future if needed.		This is a good visual reminder to bump in the future if needed.

	== For upgrades it's ok to use OE for inspiration ==		== For upgrades it's ok to use OE-Classic for inspiration ==

	When upgrading packages, do the git mv as above, and build if it breaks, it's OK to check the OE equivalent and grab new patch or configuration change, just don't grab the whole recipe.		When upgrading packages, do the git mv as above, and build if it breaks, it's OK to check the OE-Classic equivalent and grab new patch or configuration change, just don't grab the whole recipe.

	Be sure to add a credit to OE in your commit message when you do take a change like this.		Be sure to add a credit to OE-Classic in your commit message when you do take a change like this.

	Review: [[Merging packages from OpenEmbedded]]		Review: [[Merging packages from OpenEmbedded]]
Line 23:		Line 23:
	== For new package grab OE version, but sanitize it ==		== For new package grab OE version, but sanitize it ==

	Follow the recipe rules for Yocto when you take an OE recipe, be sure to clean ~~all~~ the ~~OE'isms out~~		Follow the recipe rules for Yocto when you take an OE-Classic recipe, be sure to clean out obsolete parts of the recipe and apply the new rules.

	Again, give credit to OE in commit messages		Again, give credit to OE in commit messages
Line 31:		Line 31:
	== Do not merge .inc / .bb files ==		== Do not merge .inc / .bb files ==

	We do not want to merge the common ".inc" files and recipe (.bb) files. This is the case even if the .bb only contains a require and a PR = "r0" line. Leaving the .inc file separate allows other layers to re-use the .inc file for older/newer versions.		We do not want to merge the common ".inc" files and recipe (.bb) files together. This is the case even if the .bb only contains a require and a PR = "r0" line. Leaving the .inc file separate allows other layers to re-use the .inc file for older/newer versions.

	== White Space Management ==		== White Space Management ==
Line 62:		Line 62:
	=== Patch Upstreaming ===		=== Patch Upstreaming ===

	In order to keep track of patches and ultimate reduce the number of patches that the ~~Yotco~~ Project maintains, we need to track the status of the patches that are created. As mentioned above, we the patches to contain comments about why they are created, by whom and when, we also want to track if it's appropriate to get this particular patch into the upstream project. Since we want to track this information, we need a consistent tag and set of status that can be searched. Be sure to include any URL to bug tracking, mailing list or other reference material pertaining to the patch.		In order to keep track of patches and ultimate reduce the number of patches that the Yocto Project maintains, we need to track the status of the patches that are created. As mentioned above, the patches should contain comments about why they are created, by whom and when, we also want to track if it's appropriate to get this particular patch into the upstream project. Since we want to track this information, we need a consistent tag and set of status that can be searched. Be sure to include any URL to bug tracking, mailing list or other reference material pertaining to the patch.

	'''Upstream-Status:'''		'''Upstream-Status:'''

PaulEggleton: Tidy up some language and remove extraneous discussion

2011-07-21T15:35:57Z

Tidy up some language and remove extraneous discussion

← Older revision		Revision as of 15:35, 21 July 2011
Line 1:		Line 1:
	This page is used for capturing the Best Known Methods (BKMs) of package upgrading as we get reviewed and process more of the packages.		This page is used for capturing the Best Known Methods (BKMs) of package upgrading as we get reviewed and process more of the packages.

	== Don't ~~Retain~~ older ~~Versions~~ ==		== Don't retain older versions ==

	Unless there is a specific need (~~which will probably occur~~ for GPLv2, ~~this has also happened in the past when platforms have~~ known bugs in the latest version) don't retain older versions of the recipe files and patches.		Unless there is a specific need (for GPLv2, or where there are known serious bugs in the latest version) don't retain older versions of the recipe files and patches.

	== Use git mv ~~to rename recipe and patches~~ ==		== Use git mv for version updates ==

	~~From Josh:~~		Use "git mv" to rename the old file to the new version - this means that you don't have to consciously delete the old version later.
	~~Generally the way I perform recipe upgrades is to use~~ git mv to rename the old file to the new version, this means that you don't have to consciously delete the old version later ~~(win 1) and that git tracks the rename and the differences with the old file, which doesn't happen with a delete and add (win 2)~~.

	~~The advantage of this is that you and any reviewers can more easily see what has changed with the updated version of the recipe.~~		== Reset PR to r0 (or add PR = "r0") when upgrading recipes ==


	Nitin: Actually {git mv a b} is nothing but {mv a b; git rm a; git add b} And the file renames are detected by git automatically by looking at the file contents. Because of this git behavior, git shows some renames as renames and sometimes not. And I did not find a way to force git to understand renames. So if after "git mv" git is showing "file add & file remove", then don't get surprised, it's normal git operation.

	=== Reset PR to 0 (or add PR) when upgrading recipes ===

	This is a good visual reminder to bump in the future if needed.		This is a good visual reminder to bump in the future if needed.
Line 27:		Line 21:
	Review: [[Merging packages from OpenEmbedded]]		Review: [[Merging packages from OpenEmbedded]]

	== For new package grab OE version, but sanitize ~~them~~ ==		== For new package grab OE version, but sanitize it ==

	Follow the recipe rules for Yocto when you take an OE recipe, be sure to clean all the OE'isms out		Follow the recipe rules for Yocto when you take an OE recipe, be sure to clean all the OE'isms out
Line 35:		Line 29:
	Review: [[Merging packages from OpenEmbedded]]		Review: [[Merging packages from OpenEmbedded]]

	== Do ~~NOT Merge~~ .inc / .bb files ==		== Do not merge .inc / .bb files ==

	~~This was a decision that slipped by me, and was not communicated well, we~~ do not want to merge the common ".inc" files and recipe (.bb) files. This is the case even if the .bb only contains a require and a PR="r0" line. ~~This does not mean split everything at this point, but don't merge going forward~~.		We do not want to merge the common ".inc" files and recipe (.bb) files. This is the case even if the .bb only contains a require and a PR = "r0" line. Leaving the .inc file separate allows other layers to re-use the .inc file for older/newer versions.

	== White Space Management ==		== White Space Management ==


	* Most variables such as SRC_URI should use spaces.		* Most variables such as SRC_URI should use spaces.
Line 54:		Line 47:
	=== Patch Comments ===		=== Patch Comments ===

	Patch comments should ~~contains~~ information about why the patch is required, who created the patch and when~~, if~~ that information is not currently ~~know~~ the the ~~last~~ information about where the patch came from (such as from OpenEmbedded) is very important to maintain in the patch header. Having a Signed-off-by: tag is good to acknowledge that someone looked at the patch and added the comments to ensure it is still valid and current.		Patch comments should contain information about why the patch is required, who created the patch and when. If that information is not currently known, the the information about where the patch last came from (such as from OpenEmbedded) is very important to maintain in the patch header. Having a Signed-off-by: tag is good to acknowledge that someone looked at the patch and added the comments to ensure it is still valid and current.

	To recap, patches should contain:		To recap, patches should contain:
	* Why		* Why
	* Date ~~Created~~		* Date created
	* Who ~~Created~~ it		* Who created it
	* Any ~~Upstream~~ information		* Any upstream information
	** link to upstream mailing list		** link to upstream mailing list
	** link to upstream bug tracking		** link to upstream bug tracking
Line 133:		Line 126:

	* The LICENSE information in the .bb file needs to be practical.		* The LICENSE information in the .bb file needs to be practical.
	* if there's "or any later version" in GPL related ~~copyright~~, append "+" then which effectively means below:		* if there's "or any later version" in GPL related notices, append "+" then which effectively means below:
	GPLv2, GPLv2+, GPLv3, GPLv3+, LGPLv2, LGPLv2+, LGPLv2.1, LGPLv2.1+, LGPLv3, LGPLv3+		GPLv2, GPLv2+, GPLv3, GPLv3+, LGPLv2, LGPLv2+, LGPLv2.1, LGPLv2.1+, LGPLv3, LGPLv3+
	* Scripts generated by autotools are not counted for licensing (they are always under GPL)		* Scripts generated by autotools are not counted for licensing (they are always under GPL)

SaulWold: /* Patch Upstreaming */

2011-04-07T00:39:53Z

Patch Upstreaming

← Older revision		Revision as of 00:39, 7 April 2011
Line 87:		Line 87:
	:::: native		:::: native
	:::: licensing		:::: licensing
			:::: configuration
	:::: enable feature		:::: enable feature
	:::: disable feature		:::: disable feature

SaulWold: /* Patch Upstreaming */

2011-04-05T19:27:21Z

Patch Upstreaming

← Older revision		Revision as of 19:27, 5 April 2011
Line 72:		Line 72:

	'''Upstream-Status:'''		'''Upstream-Status:'''
			:;Pending
			:: No determination has been made yet or not yet submitted to upstream
	:;Submitted		:;Submitted
	:: Submitted to upstream, waiting approval		:: Submitted to upstream, waiting approval

SaulWold: /* Patch Upstreaming */

2011-04-05T18:35:16Z

Patch Upstreaming

← Older revision		Revision as of 18:35, 5 April 2011
Line 80:		Line 80:
	:;Denied		:;Denied
	:: Not accepted by upstream, include reason in patch		:: Not accepted by upstream, include reason in patch
	:;~~Poky-Specific~~		:;Inappropriate [reason]
	:: The patch ~~is specific to Poky and~~ is not appropriate for upstream		:: The patch is not appropriate for upstream, include a brief reason on the same line enclosed with []
			::: '''reason''' can be:
			:::: native
			:::: licensing
			:::: enable feature
			:::: disable feature
			:::: bugfix (add bug url here)
			:::: embedded specific
			:::: other (give details in comments)

			All patches and diff files should include this information.

	== New style patch application ==		== New style patch application ==

SaulWold at 17:32, 5 April 2011

2011-04-05T17:32:45Z

@@ Line 69: / Line 69: @@
 === Patch Upstreaming ===
-In order to keep track of patches and ultimate reduce the number of patches that the Yotco Project maintains, we need to track the status of the patches that are created. As mentioned above, we the patches to contain comments about why they are created, by whom and when, we also want to track if it's appropriate to get this particular patch into the upstream project. Since we want to track this information, we need a consistent tag and set of status that can be searched. These are defined here.
+In order to keep track of patches and ultimate reduce the number of patches that the Yotco Project maintains, we need to track the status of the patches that are created. As mentioned above, we the patches to contain comments about why they are created, by whom and when, we also want to track if it's appropriate to get this particular patch into the upstream project. Since we want to track this information, we need a consistent tag and set of status that can be searched. Be sure to include any URL to bug tracking, mailing list or other reference material pertaining to the patch.
 == New style patch application ==

SaulWold: /* Patch Upstreaming */

2011-04-05T17:19:40Z

Patch Upstreaming

← Older revision		Revision as of 17:19, 5 April 2011
Line 69:		Line 69:
	=== Patch Upstreaming ===		=== Patch Upstreaming ===

	In order to keep track of patches and ultimate reduce the number of patches that the Yotco Project maintains, ... ~~more to come~~		In order to keep track of patches and ultimate reduce the number of patches that the Yotco Project maintains, we need to track the status of the patches that are created. As mentioned above, we the patches to contain comments about why they are created, by whom and when, we also want to track if it's appropriate to get this particular patch into the upstream project. Since we want to track this information, we need a consistent tag and set of status that can be searched. These are defined here.

	== New style patch application ==		== New style patch application ==