[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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



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 <spwhitton@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

Attachment: signature.asc
Description: PGP signature


Reply to: