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

From Yocto Project
Jump to navigationJump to search
(Added definitions of distro tracking fields)
 
(10 intermediate revisions by 3 users not shown)
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 ==


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.
== Remove PR when upgrading recipes ==


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


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.
== Do not merge .inc / .bb files ==


=== Reset PR to 0 (or add PR) when upgrading recipes ===
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.


This is a good visual reminder to bump in the future if needed.
== Style guidelines ==


== For upgrades it's ok to use OE for inspiration ==
See the [http://openembedded.org/wiki/Styleguide OpenEmbedded style guide].


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.
== Patches ==


Be sure to add a credit to OE in your commit message when you do take a change like this.
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.


Review: [[Merging packages from OpenEmbedded]]
=== Patch Comments ===


== For new package grab OE version, but sanitize them ==
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.


Follow the recipe rules for Yocto when you take an OE recipe, be sure to clean all the OE'isms out
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


Again, give credit to OE in commit messages
=== Patch Upstreaming ===


Review: [[Merging packages from OpenEmbedded]]
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.


== Do NOT Merge .inc / .bb files ==
'''Upstream-Status:'''
:;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)


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.
All patches and diff files should include this information.
 
== White Space Management ==
 
 
* Most variables such as SRC_URI should use spaces.
 
* Shell functions should use tabs
 
* Python functions should use spaces (4 spaces per indent).
 
== Commenting in Patches ==
 
When you change or add patches, be sure to include attributions of where the patch came from, along with your full name and email similar to "Signed-off-by", no special tag is needed (yet?), but having your full name and email is important to track it.
 
== New style patch application ==
 
The patch and pnum parameters have been renamed to the more logical apply and striplevel. The apply parameter takes either "yes" or "no" and the striplevel parameter takes an integer (0, 1, etc).
 
Both parameters are now optional with "sane" defaults.
 
The apply parameter is optional for SRC_URI lines with patch or diff extensions, which will default to being applied.
 
The striplevel parameter is also optional with a default striplevel of 1.
 
Old style parameters (patch and pnum) will continue to work for some time but it would be useful to move to the new style syntax as people are updating other parts of their recipes.
 
Therefore a patch line would be changed from:
 
file://some.patch;patch=1;pnum=2
 
to:
 
file://some.patch;striplevel=2
 
and a patch line:
 
file://another.diff;patch=1;pnum=1
 
could be changed to:
 
file://another.diff


== Recipe Metadata Updates ==
== Recipe Metadata Updates ==
=== DESCRIPTION and SUMMARY ===
<Mark Hatle Can you please comment here>


=== LICENSE Metadata ===
=== LICENSE Metadata ===


* The LICENSE information in the .bb file needs to be practical.
See [http://openembedded.org/wiki/Recipe_License_Fields Recipe License Fields] on the OE wiki.
* if there's "or any later version" in GPL related copyright, append "+" then which effectively means below:
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)
* Dual license: GPLv2 | BSD
* Multiple licenses: GPLv3+ & LGPLv2.1+
* GPLv3 (correction may be required!)
anti-tivoization in GPLv3 only applies to User Products, which per definition is “either
(1) a “consumer product”, which means any tangible personal property which is normally
used for personal, family, or household purposes, or (2) anything designed or sold for
incorporation into a dwelling."
* For package changing its license, better to keep new license in .inc file with old license in corresponding .bb file. Take readline for example:
readline.inc: LICENSE = "GPLv3+"
readline_5.2.bb: LICENSE = "GPLv2"
* we can treat MIT-style license as "MIT", meaning that any lawyer can tell it derivatives from standard form, such as below one:
 
Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
the above copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation, and
that the name of the copyright holders not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission.  The copyright holders make no representations
about the suitability of this software for any purpose.  It is provided "as
is" without express or implied warranty.
* some package may have complex license, such as wireless-tool:
most of files are GPLv2;
one part in file is GPLv2+;
some of them are dual licensed, such as sample_enc.c under LGPL | MPL | BSD.
In such case, first ignore the GPLv2+ bit since there is no way you could ever ship the package under say GPLv3 due to many headers being v2 only.
Since there are files that are GPLv2 only, the answer is no. The LICENSE field is therefore primarily GPLv2 and we can ignore the 2+ bits.
If they're a key part, the recipe becomes "GPLv2 & (LGPL | MPL | BSD)"
* automake may generate COPYING automatically if there's no such one existing (e.g. Xsettings-client-0.10). A short answer is to add a MIT-style COPYING in poky and then install it before autotools work. See last section for detail description
* all .bb files require LICENSE fields, even for those Poky specific (which are MIT).
* ask on the ML for license information for those local files we don't know their origins
* Name Sub-Packages with different Licenses
** LICENSE = "LGPLv2.1 & GPLv3+"
** LICENSE_libidn = "LGPLv2.1"
** LICENSE_libidn-tests = "GPLv3+"
* when listing sub-package license, remember to use names included in PACKAGES instead of source directories, e.g:
LICENSE = "GPLv2 & LGPLv2 & BSD & MIT"
LICENSE_lib/ext2fs = "LGPLv2"
Better to use:
LICENSE_e2fsprogs-mke2fs = "LGPLv2"
because mke2fs is a package name
----
* Two variants of the license, the New BSD License/Modified BSD License, and the Simplified BSD License/FreeBSD License have been verified as GPL-compatible free software licenses by the Free Software Foundation, while the original has not been accepted as an open source license(http://en.wikipedia.org/wiki/Original_BSD_license#4-clause)
* The original BSD license also includes a clause requiring all advertising of the software to display a notice crediting its authors. This "advertising clause" (since disavowed by UC Berkeley) is present in the modified MIT License used by XFree86 (http://en.wikipedia.org/wiki/MIT_License)
* http://en.wikipedia.org/wiki/Comparison_of_free_software_licenses
* http://www.opensource.org/licenses/alphabetical
* http://www.gnu.org/licenses/license-list.html
 
==== Autotools adds wrong COPYING ====
 
Autotools add the wrong COPYING license to source code with out COPYING, to ensure that we have the correct and consistent license, add the correct license file to the SRC_URI List and a do_config_prepend().
 
SRC_URI = "... \
        ...
        file://XXX-license"
do_configure_prepend() {
        # This package doesn't ship with its own COPYING file and
        # autotools will install a GPLv2 one instead of MIT. Add the
        # correct license here to avoid confusion.
        cp ${WORKDIR}/MIT-style-license ${S}/COPYING
}


== Distro Tracking Fields ==
== Distro Tracking Fields ==


The file meta/conf/distro/include/distro_tracking_fields.inc exists 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:
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_STATUS
;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_DEPENDENCY_CHECK
;RECIPE_UPSTREAM_VERSION
: Indicates whether the recipe has been built from scratch to verify that all of its build and runtime dependencies have been specified. Value is either "not done" or "done"
: The latest upstream stable version
;RECIPE_LATEST_VERSION
;RECIPE_UPSTREAM_DATE
: The latest upstream stable version, "3.0"
: The date at which the latest upstream stable version (mentioned in RECIPE_UPSTREAM_VERSION) was released, "Mar 3, 2013"
;RECIPE_NO_OF_PATCHES
: The number of patches we ship with the recipe.
;RECIPE_PATCH
: Summarizes the purpose of each patch associated with a recipe.
;RECIPE_LATEST_RELEASE_DATE
: The date at which the upstream stable release (mentioned in RECIPE_LATEST_VERSION) was released, "03/2010"
;RECIPE_TIME_BETWEEN_LAST_TWO_RELEASES
: The amount of time which passed between the most recent two upstream stable releases, "2 months"
;RECIPE_COMMENTS
: A field to mention comments, such as why a recipe can't be brought up to the latest upstream release, or unusual build issues that need to be worked around.
;RECIPE_LAST_UPDATE
: Date of the last changes to the recipe, "Dec 10, 2010"
;RECIPE_MAINTAINER
;RECIPE_MAINTAINER
: Name and email address of the person maintaining the recipe, "Firstname Lastname <email.address>"
: 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 file, each field name is appended with -pn-<recipe name>.
Note that in the files, each field name is appended with _pn-<recipe name>.

Latest revision as of 13:16, 10 June 2014

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.

Upstream-Status:

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.

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=13001"