diff --git a/man/os-release.xml b/man/os-release.xml index a00b8a5264a..52323df6c7d 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -224,12 +224,13 @@ BUILD_ID= - A string uniquely identifying the system image used as the origin for a distribution - (it is not updated with system updates). The field can be identical between different - VERSION_IDs as BUILD_ID is an only a unique identifier to a - specific version. Distributions that release each update as a new version would only need to use - VERSION_ID as each build is already distinct based on the - VERSION_ID. This field is optional. + A string uniquely identifying the system image originally used as the installation + base. In most cases, VERSION_ID or + IMAGE_ID+IMAGE_VERSION are updated when the entire system + image is replaced during an update. BUILD_ID may be used in distributions where + the original installation image version is important: VERSION_ID would change + during incremental system updates, but BUILD_ID would not. This field is + optional. Examples: BUILD_ID="2013-03-20.3", BUILD_ID=201303203. @@ -261,6 +262,13 @@ + + To summarize: if the image updates are built and shipped as comprehensive units, + IMAGE_ID+IMAGE_VERSION is the best fit. Otherwise, if updates + eventually completely replace previously installed contents, as in a typical binary distribution, + VERSION_ID should be used to identify major releases of the operating system. + BUILD_ID may be used instead or in addition to VERSION_ID when + the original system image version is important.