Hi Russ, On Thu, Apr 01, 2021 at 06:17:59PM -0700, Russ Allbery wrote: > Here is an updated diff that documents the most well-understood version > conventions in the Debian archive. More could certainly be added; this is > just a first start that addresses this specific bug. thank you for this, I've reviewed it and am generally very happy with these changes. > This revised patch is less aggressive about defining native packages to > only mean packages with no existence external to Debian. I'm not sure if in this regard I would have liked the previous version better, as the paragraph about native packages is the only one which I would like to see extended to explain that it has been observed that packages we thought were native to Debian were not really native to Debian at all and require modifications in Debian downstream distributions, which are harder to do when the packages are native (eg modified orig.tar's despite no upstream changes). src:piuparts is one example for this where this is even annoying within Debian, as eg piuparts 1.1.2 was uploaded to sid and then that orig tarball cannot be used for the upload to backports. Also big/huge native packages are also annoying to maintain when one has to do small packaging changes and each time has to upload huge orig.tar. This was annoying when src:debian-edu-artwork was 50-100mb and native, today that package is 8mb and non-native. > I think this change is ready for seconds. All that said, I'm still happy to second this! :) > diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst > index a21a510..cd7daaa 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 > @@ -646,6 +643,83 @@ 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. > + > +- ``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. > + > +- ``upstream_version`` components in native packages or > + ``debian_revision`` components in non-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 > + 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-5``. If that package later receives a stable update in Debian 10, > + the first update would have the version ``1.4-5+deb10u1``. A subsequent > + update would have version ``1.4-5+deb10u2``. These numbers are designed > + to sort earlier than ``1.4-6``, the version number that would be used > + for the next unstable upload. > + > +- ``upstream_version`` components in native packages or > + ``debian_revision`` components in non-native packages ending in > + ``~debNuX`` also indicate a stable update, but of a different type. > + This version convention indicates that the stable version of the package > + was updated to a new upstream release, as distinct from the ``+debNuX`` > + convention that indicates additional changes were applied to the > + existing stable release. ``N`` and ``X`` mean the same as with > + ``+debNuX``. > + > + For example, suppose Debian 10 released with a package with version > + ``1.4-5``, and then suppose a new upstream release was later packaged as > + ``1.5-1``. In some exceptional circumstances, it may make sense to > + replace the stable version of the package with a package based on the > + upstream ``1.5`` release and ``1.5-1`` Debian package instead of trying > + to apply patches to the ``1.4-5`` version. In this case, the new stable > + package would have version ``1.5-1~deb10u1``. This number is designed > + to sort earlier than ``1.5-1``, the version number that would be used > + for the unstable upload. > + > +- ``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. > + > + This version convention was chosen to sort before the original package > + release that is being backported, so that the backport will upgrade to > + the original package during a later system upgrade to a newer Debian > + release. > + > +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. -- cheers, Holger ⢀⣴⠾⠻⢶⣦⠀ ⣾⠁⢠⠒⠀⣿⡁ holger@(debian|reproducible-builds|layer-acht).org ⢿⡄⠘⠷⠚⠋⠀ PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C ⠈⠳⣄ Some people say that the climate crisis is something that we all have created, but that is not true, because if everyone is guilty then no one is to blame. And someone is to blame. Some people, some companies, some decision-makers in particular, have known exactly what priceless values they have been sacrificing to continue making unimaginable amounts of money. (Greta Thunberg)
Attachment:
signature.asc
Description: PGP signature