Best Known Methods (BKMs) for Package Updating: Difference between revisions

From Yocto Project
Jump to navigationJump to search
(Remove/replace old, outdated or duplicated information)
 
(One intermediate revision by one other user not shown)
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.
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.
:;Pending
:: No determination has been made yet or not yet submitted to upstream
:;Submitted
:: Submitted to upstream, waiting approval
:;Accepted
:: Accepted in upstream, expect it to be removed at next update, include expected version info
:;Backport
:: Backported from new upstream version, because we are at a fixed version, include upstream version info
:;Denied
:: Not accepted by upstream, include reason in patch
:;Inappropriate [reason]
:: The patch is not appropriate for upstream, include a brief reason on the same line enclosed with []
::: '''reason''' can be:
:::: native
:::: licensing
:::: configuration
:::: 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.
All patches and diff files should include this information.
Line 81: Line 60:
;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

Latest revision as of 15:35, 12 March 2025

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

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 for version updates

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.

Remove PR when upgrading recipes

PR values are now expected to be managed by the PR server.

Do not merge .inc / .bb files

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.

Style guidelines

See the OpenEmbedded style guide.

Patches

Patches should contain information about where they came from and why they are required, as the project moves forward, we want to increase the quality of the data that is made available to the community. This can be done in the recipes and also in the patch files in order to understand why the patch exists and to help future maintainer to understand why it is required.

Patch Comments

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:

  • Why
  • Date created
  • Who created it
  • Any upstream information
    • link to upstream mailing list
    • link to upstream bug tracking
    • IRC info
  • Signed-off-by:
    • This is most important when importing the patch and not the original author

Patch Upstreaming

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.

The complete list of patch status fields can be found in the Recipe Style Guide documentation.

All patches and diff files should include this information.

Recipe Metadata Updates

LICENSE Metadata

See Recipe License Fields on the OE wiki.

Distro Tracking Fields

The meta/conf/distro/include/*.inc files exist to allow us to track various pieces of information about recipes and upstream versions (e.g, recipe maintainer contact information, date of latest upstream release, alternate names used for this recipe in other Linux distros, etc). The following defines the meaning of each field:

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.
RECIPE_UPSTREAM_VERSION
The latest upstream stable version
RECIPE_UPSTREAM_DATE
The date at which the latest upstream stable version (mentioned in RECIPE_UPSTREAM_VERSION) was released, "Mar 3, 2013"
RECIPE_MAINTAINER
Name and email address of the person maintaining the recipe, "Firstname Lastname <email.address>"
RECIPE_NO_UPDATE_REASON
Reason for not updating the recipe to a later version if applicable
DISTRO_PN_ALIAS
A list mapping package names for tracking status of package relative to major distributions such as Fedora, Ubuntu, Debian

Note that in the files, each field name is appended with _pn-<recipe name>.

Retrieved from "https://wiki.yoctoproject.org/wiki/index.php?title=Best_Known_Methods_(BKMs)_for_Package_Updating&oldid=86584"