Simon McVittie <s...@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 (r...@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
