diff options
| author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2021-05-20 20:37:55 +0200 |
|---|---|---|
| committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2021-05-21 17:06:28 +0200 |
| commit | 8fd67ab5a38822475c79f3d2d7864585a7898f59 (patch) | |
| tree | 429a619791fb785aa4b790a1588b29c210a640ed /man | |
| parent | man: add example os-release mangling in python (diff) | |
| download | systemd-8fd67ab5a38822475c79f3d2d7864585a7898f59.tar.xz systemd-8fd67ab5a38822475c79f3d2d7864585a7898f59.zip | |
man: reword description of BUILD_ID in os-release
Our description was pretty hard to parse. Let's replace it with a description
loosely based on a fairly clear description written by a distro that actually
uses BUILD_ID:
https://developer.rigado.com/docsets/Working-with-the-Rigado-Vesta-Gateway/latest/production/versioning-images.html#the-rigos-scheme.
Diffstat (limited to 'man')
| -rw-r--r-- | man/os-release.xml | 20 |
1 files changed, 14 insertions, 6 deletions
diff --git a/man/os-release.xml b/man/os-release.xml index a00b8a5264..52323df6c7 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -224,12 +224,13 @@ <varlistentry> <term><varname>BUILD_ID=</varname></term> - <listitem><para>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 - <varname>VERSION_ID</varname>s as <varname>BUILD_ID</varname> is an only a unique identifier to a - specific version. Distributions that release each update as a new version would only need to use - <varname>VERSION_ID</varname> as each build is already distinct based on the - <varname>VERSION_ID</varname>. This field is optional.</para> + <listitem><para>A string uniquely identifying the system image originally used as the installation + base. In most cases, <varname>VERSION_ID</varname> or + <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> are updated when the entire system + image is replaced during an update. <varname>BUILD_ID</varname> may be used in distributions where + the original installation image version is important: <varname>VERSION_ID</varname> would change + during incremental system updates, but <varname>BUILD_ID</varname> would not. This field is + optional.</para> <para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>. </para></listitem> @@ -261,6 +262,13 @@ </para></listitem> </varlistentry> </variablelist> + + <para>To summarize: if the image updates are built and shipped as comprehensive units, + <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> is the best fit. Otherwise, if updates + eventually completely replace previously installed contents, as in a typical binary distribution, + <varname>VERSION_ID</varname> should be used to identify major releases of the operating system. + <varname>BUILD_ID</varname> may be used instead or in addition to <varname>VERSION_ID</varname> when + the original system image version is important.</para> </refsect2> <refsect2> |