Bug#542288: debian-policy: Version numbering: native packages, NMU's, and binary only uploads

[Russ Allbery <rra@debian.org>]

Simon McVittie <smcv@debian.org> writes:

> The other way is to repackage the new upstream release from first
> principles, either because it's a new release from an upstream branch
> that's older than the one in testing/unstable (like src:flatpak in
> Debian 10), or because testing/unstable already has packaging changes
> that aren't suitable for stable (like src:dbus in Debian 10). In this
> case it would be misleading to use a version number like
> flatpak_1.2.5-1~deb10u1 (because 1.2.5-1 never existed) or
> dbus_1.12.20-1~deb10u1 (because 1.12.20-1 did exist, but the version of
> dbus in stable was not based on it, and does not have the downstream
> changes from that version). Instead, the convention that has emerged is
> to use 0+deb10u1, by analogy with the convention that an NMU introducing
> a new upstream release has revision number 0.1.

Ah, thanks for this.  I wasn't aware this convention existed.

Here's a new draft, which is unfortunately quite a bit longer because it's
hard to make this clear.  I also added the +really convention explicitly,
since it's mentioned immediately above, and noted that the stable update
and backport conventions can, in rare circumstances, stack.

-- 
Russ Allbery (rra@debian.org)              <https://www.eyrie.org/~eagle/>

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index a21a510..2fd6868 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -582,20 +582,17 @@ The three components here are:
     alphanumerics and the characters ``+`` ``.`` ``~`` (plus, full stop,
     tilde) and is compared in the same way as the ``upstream_version`` is.
 
-    It is optional; if it isn't present then the ``upstream_version``
-    may not contain a hyphen. This format represents the case where a
-    piece of software was written specifically to be a Debian package,
-    where the Debian package source must always be identical to the
-    pristine source and therefore no revision indication is required.
+    It is conventional to restart the ``debian_revision`` at ``1`` each
+    time the ``upstream_version`` is increased.
 
-    It is conventional to restart the ``debian_revision`` at ``1``
-    each time the ``upstream_version`` is increased.
+    The package management system will break the version number apart at
+    the last hyphen in the string (if there is one) to determine the
+    ``upstream_version`` and ``debian_revision``. The absence of a
+    ``debian_revision`` is equivalent to a ``debian_revision`` of ``0``.
 
-    The package management system will break the version number apart
-    at the last hyphen in the string (if there is one) to determine
-    the ``upstream_version`` and ``debian_revision``. The absence of a
-    ``debian_revision`` is equivalent to a ``debian_revision`` of
-    ``0``.
+    Presence of the ``debian_revision`` part indicates this package is a
+    non-native package (see :ref:`s-source-packages`).  Absence indicates
+    the package is a native package.
 
 When comparing two version numbers, first the epoch of each are
 compared, then the ``upstream_version`` if epoch is equal, and then
@@ -625,6 +622,8 @@ These two steps (comparing and removing initial non-digit strings and
 initial digit strings) are repeated until a difference is found or both
 strings are exhausted.
 
+.. _s-avoid-epochs:
+
 Epochs should be used sparingly
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -639,13 +638,132 @@ Epochs should not be used when a package needs to be rolled back.
 In that case, use the ``+really`` convention: for example, if you
 uploaded ``2.3-3`` and now you need to go backwards to upstream 2.2,
 call your reverting upload something like ``2.3+really2.2-1``.
-Eventually, when we upload upstream 2.4, the +really part can go away.
+Eventually, when we upload upstream 2.4, the ``+really`` part can go away.
 
 Epochs are also not intended to cope with version
 numbers containing strings of letters which the package management
 system cannot interpret (such as ``ALPHA`` or ``pre-``), or with silly
 orderings.  [#]_
 
+Special version conventions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following special version numbering conventions are used in the Debian
+archive:
+
+- The absence of ``debian_revision``, and therefore of a hyphen in the
+  version number, indicates that the package is native.
+
+- The presence of ``+really`` in the ``upstream_version`` component
+  indicates that a newer upstream version has been rolled back to an older
+  upstream version.  The part of the ``upstream_version`` component
+  following ``+really`` is the true upstream version.  See
+  :ref:`s-avoid-epochs` for an example of when this is used.
+
+Non-maintainer uploads:
+
+- ``debian_revision`` components ending in ``.`` (period) followed by a
+  number indicate this version of the non-native package was uploaded by
+  someone other than the maintainer (an NMU or non-maintainer upload).
+  This is used for a source package upload; for uploads of only binary
+  packages without source changes, see the binary NMU convention below.
+
+- ``upstream_version`` components in native packages ending in ``+nmu``
+  followed by a number indicate an NMU of a native package.  As with the
+  convention for non-native packages, this is used for a source package
+  upload, not for uploads of only binary packages without source changes.
+
+- ``upstream_version`` components in native packages or
+  ``debian_revision`` components in non-native packages ending in ``+b``
+  followed by a number indicate a binary NMU: an upload of a binary
+  package without any source changes and hence without any corresponding
+  source package upload or version change.
+
+Stable updates:
+
+- ``upstream_version`` components in native packages ending in ``+debNuX``
+  indicate a stable update.  This is a version of the package uploaded
+  directly to a stable release, and the version is chosen to sort before
+  any later version of the package uploaded to Debian's unstable or a
+  later stable distribution.  ``N`` is the major version number of the
+  Debian stable release to which the package was uploaded, and ``X`` is a
+  number, starting at 1, that is increased for each stable upload of this
+  package.
+
+  For example, suppose Debian 10 released with a package with version
+  ``1.4``.  The first stable update of that package would have the version
+  ``1.4+deb10u1``, and a subsequent update would have the version
+  ``1.4+deb10u2``.  These versions are chosen to sort before ``1.5`` (the
+  next unstable version) or ``1.4+deb11u1`` (a stable update to a
+  subsequent Debian 11 release).
+
+- ``debian_revision`` components in non-native packages ending in
+  ``debNuX`` also indicate a stable update.  Either ``~`` or ``+`` will be
+  used before this string depending on the details of the update.  As with
+  native packages, ``N`` is the major version number of the Debian stable
+  release to which the package was uploaded, and ``X`` is a number,
+  starting at 1, that is increased for each stable upload of this package.
+
+  There are three cases for non-native packages:
+
+  #. For stable updates that use the same upstream version, the
+     ``debian_revision`` component will end in ``+debNuX``.  The portion
+     of the version before that string is the original package version in
+     the stable release.
+
+  #. For stable updates to a new upstream version that is based on a newer
+     unstable package, the ``debian_revision`` component will end in
+     ``~debNuX``.  The portion before that string will be the unstable
+     version on which the package is based.
+
+  #. If a stable update is based on a new upstream version but is not
+     based on a newer unstable package, the convention is to form the
+     version number by taking the upstream version, appending ``-0``, and
+     then appending ``+debNuX`` (so the ``debian_revision`` component will
+     be ``0+debNuX``).
+
+  In all cases, these versions are chosen so that they will sort earlier
+  than a subsequent unstable package of the same upstream version and thus
+  that the stable package will upgrade to a newer version during a
+  subsequent system upgrade.
+
+  For example, suppose Debian 10 released with a package with version
+  ``1.4-5``.  If that package later receives a stable update in Debian 10
+  that uses the same upstream version, the first update would have the
+  version ``1.4-5+deb10u1``.  A subsequent update would have version
+  ``1.4-5+deb10u2``.
+
+  If instead the package receives a stable update based on a ``1.5-1``
+  unstable package, the first such stable update would have the version
+  ``1.5-1~deb10u1`` and a subsequent update would have the version
+  ``1.5-1~deb10u2``.
+
+  If there were no unstable ``1.5-1`` package, but there were a stable
+  update to an upstream 1.5 release, the first such stable update would
+  have the version ``1.5-0+deb10u1``.
+
+Backports:
+
+- ``upstream_version`` components in native packages or
+  ``debian_revision`` components in non-native packages ending in
+  ``~bpoNuX`` indicate a backport of a version of the package to an older
+  stable release.  The part of the version before ``~bpo`` is the version
+  of the package being backported, ``N`` is the major version number of
+  the Debian stable release to which the package was backported, and ``X``
+  is a number, starting at 1, that is increased for each revision of the
+  backport of that package version.  The rationale is the same as for
+  stable updates, with the additional goal of ensuring a backported
+  version sorts earlier than a stable update with the same upstream
+  version.
+
+  Be aware that the stable update and backport conventions can stack.  If,
+  for example, Debian 10 contains a package with version ``1.4-5+deb10u1``
+  and that package is backported to Debian 9, the version of the Debian 9
+  backport would be ``1.4-5+deb10u1~bpo9u1`` (although this scenario is
+  rare).
+
+This list of version conventions is not exhaustive.
+
 .. _s-f-Description:
 
 ``Description``
diff --git a/policy/ch-scope.rst b/policy/ch-scope.rst
index e3db6c1..45f150f 100644
--- a/policy/ch-scope.rst
+++ b/policy/ch-scope.rst
@@ -182,6 +182,24 @@ ASCII
     first 128 `Unicode <http://www.unicode.org/>`_ characters, with the
     eighth bit always zero.
 
+upstream
+    The source of software that is being packaged, or the portion of a
+    software package that originates from outside of Debian.  For example,
+    suppose Alice writes and releases a free software package, and then
+    Bob creates a Debian package of that software package.  Alice is the
+    *upstream maintainer* (sometimes abbreviated as *upstream*) of the
+    package, Alice's releases are the *upstream releases*, and the version
+    number she puts on a release is the *upstream version*.  Bob may make
+    Debian-specific modifications to the package, and then later send
+    those modifications *upstream* to be incorporated in Alice's releases.
+
+    The packager and upstream developer may be the same person.  For
+    example, Alice may choose to package her own software for Debian.
+    However, this manual still distinguishes between the role of upstream
+    and the role of Debian packager, even when the same person is filling
+    both of those roles, since they have some implications for the details
+    of packaging.
+
 UTF-8
     The transformation format (sometimes called encoding) of
     `Unicode <http://www.unicode.org/>`_ defined by `RFC
diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index edae8c1..d6fbfc7 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -1,6 +1,37 @@
+.. _s-source-packages:
+
 Source packages
 ===============
 
+A Debian source package contains the source material used to construct one
+or more :doc:`binary packages <ch-binary>`.  A source package consists of
+a ``.dsc`` file (see :ref:`s-debiansourcecontrolfiles`), one or more
+compressed tar files, and possibly other files depending on the type and
+format of source package.  Binary packages are contructed from the source
+package via a build process defined by ``debian/rules`` and other files in
+the ``debian`` directory of the unpacked source package.
+
+Debian source packages are classified as *native* or *non-native*.
+
+A native source package is one that does not distinguish between Debian
+packaging and upstream releases.  A native source package contains a
+single tar file of source material, and the versioning does not have a
+Debian-specific component.  Native packages are normally (but not
+exclusively) used for software that has no independent existence outside
+of Debian, such as software written specifically to be a Debian package.
+
+A non-native source package separates the upstream release from the Debian
+packaging and any Debian-specific changes.  The source in a non-native
+source package is divided into one or more upstream tar files plus a
+collection of Debian-specific files.  (Depending on the format of the
+source package, those Debian-specific files may come in the form of
+another tar file or in the form of a compressed diff.)  The version of a
+non-native package has an upstream component and a Debian component, and
+there may be multiple Debian package versions associated with a single
+upstream release version and sharing the same upstream source tar files.
+
+Most source packages in Debian are non-native.
+
 .. _s-standardsversion:
 
 Standards conformance