Distro Tracking

= Motivation =
The Distro Tracking Fields (meta/conf/distro/include/distro_tracking_fields.inc) is a
location for sharing information about the status of recipes and tracking version information.
Not all of this information can be generated automatically (yet), so the manual editing is needed.
== Package Tracking Website ==
The Yocto Project hosts a package tracking website, that show information about the version and maintainership.
The webpage can be found at http://packages.yoctoproject.org
== Package Tracking Process ==
If we want to track the recipes latest status and do some upgrade work, below is the guideline. 
* Visit Packages Report System to get upgrade and manual check list.
Visit http://packages.yoctoproject.org, check the Upgrade Packages List and Manual Check Packages List, find out how many recipes you need to upgrade or manual check.
* Upgrade recipes
Please refer to: Best Known Methods(BKMS) for Package Updating
https://wiki.yoctoproject.org/wiki/Best_Known_Methods_(BKMs)_for_Package_Updating
* Update distro_tracking_fields.inc
For the explanation about fields in distro_tracking_fields.inc, please refer to https://wiki.yoctoproject.org/wiki/Distro_Tracking#Distro_Tracking_Fields
There are two fields in the distro_tracking_fields.inc, one field is RECIPE_MANUAL_CHECK_DATE, and this is for those recipes which can't be checked upstream version automatically, if you checked the upstream version manually, please update it. 
Another field is RECIPE_LAST_UPDATE, this field record your last upgrade time, you need to update this field after you upgrade the recipe.
It means that if you upgrade one recipe which on the Manual Check Packages List, you need to update those two fields at the same time.
When you decide not to upgrade one recipe, for the "git" type, please fill in the "RECIPE_NO_UPDATE_REASON " with first previous eight number, for other types, please fill in that field with the latest version you don't want to upgrade to. The report system will remove the recipe from the "need to upgrade packages" list if he detects the commit number or the latest version has existed in the "RECIPE_NO_UPDATE_REASON ".
= 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). We keep the metadata via BitBake Overrides. The following defines the meaning of each field:
;RECIPE_STATUS
: 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
: 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"
;RECIPE_LATEST_VERSION
: The latest upstream stable version, "3.0"
;RECIPE_MANUAL_CHECK_DATE
: This is the date of the last manual check for those packages that can not be checked automatically Date format is "Dec 10, 2010"
;RECIPE_NO_UPDATE_REASON
: An explaination as to why a recipe has not been updated to latest version, for example non stable or development version.
;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 latest upstream stable version (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
: Name and email address of the person maintaining the recipe, "Firstname Lastname <email.address>"
;RECIPE_DISTRO_PN_ALIAS
: See below for mre details
==== More information for using the DISTRO_PN_ALIAS variable ====
* Configuring the DISTRO_PN_ALIAS variable
Sometimes the names of the same packages are different in different linux distributions; and that
can becomes an issue for the distro_check task to check if the given recipe package exists in other
linux distros. This issue is avoided by defining per distro recipe name alias: DISTRO_PN_ALIAS
* Specifying the DISTRO_PN_ALIAS variable
 DISTRO_PN_ALIAS_pn-xset = "Fedora=xorg-x11-server-utils Ubuntu=x11-xserver-utils Debian=x11-xserver-utils Opensuse=xorg-x11"
Note that 'space' is used as delimiter here
* Tip
The current code can check if the src package for a recipe exists in the latest releases of
these distributions automatically: Fedora, OpenSuSE, Debian, Ubuntu, Mandrina
For example, this command will generate a report, listing which linux distros include the
sources for each of the poky recipe. 
 bitbake world -f -c distro_check
Note. You should have the following in your local.conf (or auto.conf):
 include conf/distro/include/distro_alias.inc
 include conf/distro/include/recipe_color.inc
 include conf/distro/include/maintainers.inc
 include conf/distro/include/upstream_tracking.inc 
 include conf/distro/include/package_regex.inc 
 INHERIT+= "distrodata"
The results will be stored in the build/tmp/log/distro_check-${DATETIME}.results file.
==== Other Distribution Package Search Tools ====
;Debian
: http://www.debian.org/distrib/packages
;Fedora
: https://admin.fedoraproject.org/pkgdb
;Ubuntu
: http://packages.ubuntu.com
;OpenSUSE
: http://packages.opensuse-community.org/
; RedHat:
: http://www.rpmfind.net/linux/RPM/
=== BitBake Overrides ===
We will create a set of BitBake Overides for DEPENDENCY_CHECK and RECIPE_STATUS with defaults of "not done" and as recipes are checked the appropriate file will be updated to contain the status, these files will then be used to generate the spreadsheet / progress report so we know where we stand.
There're also additional overrides we'd like to track for project progress:
* RECIPE_LATEST_VERSION_pn+<packagename>="x.y.z"; Override for missing or inaccurate version information from kevin’s script
* RECIPE_PATCH_pn+<packagename>+<patchname>="description/status"; Description about a patch's purpose and its status whether necessary to keep
* RECIPE_COMMENTS_pn+<packagename>="comments"; Contain micellaneous useful information about the package
* RECIPE_TIME_BETWEEN_LAST_TWO_RELEASES_pn+<packagename>="5 months"; Activity tracking information
* RECIPE_LATEST_RELEASE_DATE_pn+<packagename>="2010/03/03"; Last release date
* RECIPE_INTEL_SECTION_pn="base"; section info defined by distro team, which may replace current SECTION later