Hello, On Fri 02 Apr 2021 at 10:22AM -07, Russ Allbery wrote:
> 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 > Seconded, and I've merged your branch to next. Thanks Russ. I made some wording changes and applied Sam's suggestion to flip the ordering of non-native and native stable update versions. I'm also going ahead and applying the following patch which I'm less sure about, because possibly it loses information that you wanted to include -- please feel free to revert or iterate on it.
From f3e38e43a72af31abf9ce7bdb614eae1c47249a4 Mon Sep 17 00:00:00 2001 From: Sean Whitton <spwhit...@spwhitton.name> Date: Thu, 23 Dec 2021 23:06:50 -0700 Subject: [PATCH] introduce native source packages slightly differently Taking the definitions section in ch. 1 strictly, "upstream releases" refers to the content of upstream's releases, not the events of upstream releasing. So when we say that a native source package does not distinguish between Debian packaging and upstream releases, we mean that there is no distinction made between the debian/ directory and all the rest of the source code. This is true if we are thinking about our source package formats, where for a non-native package there are separate tarballs for debian/ and for the rest of the source code. However, the distinction between native and non-native packages is not inexorably tied to our use of source packages. If someone doesn't have source package formats in mind, the distinction between the debian/ directory and all the rest of the source code is not so salient -- in a sense, there is always *some* distinction between those, native or not. --- policy/ch-source.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/policy/ch-source.rst b/policy/ch-source.rst index d6fbfc7..65e6f9e 100644 --- a/policy/ch-source.rst +++ b/policy/ch-source.rst @@ -14,7 +14,7 @@ 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 +packaging releases 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 -- 2.30.2
-- Sean Whitton
signature.asc
Description: PGP signature
