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

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



Package: debian-policy
Version: 3.8.3.0
Severity: wishlist
User: debian-policy@packages.debian.org
Usertags: normative issue

Hi,

        Currently, there is some ambiguity in the areas of version
 numbering, debian_revision, native packages, and requirement for a
 diff.gz/orig.tar.gz files in a source package. Also, currently policy
 does not carve out version name spaces for NMU's (native and non-native
 packages), for version numbers for binary only uploads, though there
 are well established practices for these use cases.

        To recap, this is what is incontrovertibly stated in policy:

,----[ §5.6.12:  `Version' ]
|   The format is:
|      [<epoch>`:']<upstream_version>[`-'<debian_revision>]
|       <upstream_version>
|  SNIP
|           The comparison behavior of the package management system with
|           respect to the <upstream_version> is described below.  The
|           <upstream_version> portion of the version number is mandatory.
| 
|           The <upstream_version> may contain only alphanumerics[1] and the
|           characters `.'  `+' `-' `:' `~' (full stop, plus, hyphen, colon,
|           tilde) and should start with a digit.  If there is no
|           <debian_revision> then hyphens are not allowed; if there is no
|           <epoch> then colons are not allowed.
| 
|      <debian_revision>
|           This part of the version number specifies the version of the
|           Debian package based on the upstream version.  It may contain
|           only 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 turned into a
|           Debian package, and so there is only one "debianisation" of it
|           and therefore no revision indication is required.
`----

        Additionally, 
  § 5.6.21. `Files' mentions that the .dsc will contain a diff.gz if
            applicable 
  § C.1.1. `dpkg-source' states that it creates a diff.gz if
            appropriate, and looks at the diff.gz while extracting if
            applicable.

,----[ § C.3. Source packages as archives ]
|  Original source archive - `<package>_<upstream-version>.orig.tar.gz'
|       This is a compressed (with `gzip -9') `tar' file containing the
|       source code from the upstream authors of the program.
| 
|  Debianisation diff - `<package>_<upstream_version-revision>.diff.gz'
|       This is a unified context diff (`diff -u') giving the changes
|       which are required to turn the original source into the Debian
|       source.  These changes may only include editing and creating
|       plain files.  The permissions of files, the targets of symbolic
|       links and the characteristics of special files or pipes may not
|       be changed and no files may be removed or renamed.
| 
|       All the directories in the diff must exist, except the `debian'
|       sub-directory of the top of the source tree, which will be created
|       by `dpkg-source' if necessary when unpacking.
| 
|       The `dpkg-source' program will automatically make the
|       `debian/rules' file executable (see below).
| 
|  If there is no original source code - for example, if the package is
|  specially prepared for Debian or the Debian maintainer is the same as
|  the upstream maintainer - the format is slightly different: then there
|  is no diff, and the tar file is named `<package>_<version>.tar.gz', and
|  preferably contains a directory named `<package>-<version>'.
`----


        Given these, I read this as letting the tools rely on
 the following invariants, even though these are not explicitly spelled
 out in so many words in policy:

 1)  If there is a - in the version number, then the package is
     non-native
      a) the upstream version is the part of the string until the last
         '-' in the version number 
      b) there is a .orig.tar.gz and
      c) diff.gz referenced in the .dsc
 2) If there is no '-' in the version number, then the package is a
    debian native package
      a) there is no debian revision, all the version number is the
         upstream version number
      b) there is a tar.gz and no diff.gz in the .dsc file

----------------------------------------------------------------------
        Given that, it would be nice we could carve out a space in the
 version numbering that would help  us distinguish NMU's and binary
 uploads.

 1) dch --nmu adds +nmu1 for native packages
 2) +nmuX is already supported by devscripts and lintian.
 3) the developers reference also advocates adding +<codename>\d+. It
    also advocates using exactly the same tar.gz file as already in the
    archive.
 4) this is how debhelper, cdbs, and my packaging scripts handle it.

        Please also look at the discussion below, which led to
 developers reference changing its recommendation.
   http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=437392 

        I propose that we carve out a version number space that reserves
 a suffix match of
     \+nmu\d+$
 for packages that are NMU's, and make this invariant for native and
 non-native packages.

   1.0.1   --> 1.0.1+nmu1
   1.0-1   --> 1.0-1+nmu1

        And NMU's can be distinguished by a simple regexp match.
----------------------------------------------------------------------

        Similarly, for a recompilation or binary only NMU (common use
 case: outdated build environment, no source changes), the suffix can be
     \+b\d+$.
 This does require and modification of the changelog, so that the
 version number is changed (and thus the new package is used to upgrade
 the older, broken package).

   a) the developers reference already advocates this
   b) this is seen as a magic version number by the  archive maintenance
      tools, and the upload is not rejected for not having sources.

    1.0.1     --> 1.0.1+b1
    1.0-1     --> 1.0-1+b1

----------------------------------------------------------------------

        A corresponding name space can be carved out for security
 uploads. Obviously a solution would be to add +debion>.<counter>, where
 <version> should be anything that sorts correctly, such as the current
 stable version with something added if the upload is to testing.
     \+deb\d\d.\d+
     \+debt\d\d.\d+                 (testing only, sorts ahead of stable)

 where
  1.0.1   --old--> 1.0.1+etch1 --> 1.0.1+deb40
  1.0-1   --old--> 1.0.1+etch1 --> 1.0-1+deb40

        (sarge --> deb31, etch -->deb40, lenny --> deb50)

        In this case, binary only uploads sort below security uploads,
 but NMU's sort above security uploads.

This solves the use case:
  - The package version is 1.3 in all distributions.
  - A security issue is found.
  - 1.3+deb50 is uploaded to stable and testing.
  - The maintainer isn't available, and 1.3+nmu1 is uploaded to unstable.
  - Some time passes, and the package is about to migrate to testing.
  - Migration works, because 1.3+nmu1 >> 1.3+deb50.

        Using just code names is bad becase there is no ordering:
  a) 1.0-1sarge1 >> 1.0-1etch1.
  b) 1.0-1etch1 << 1.0-1lenny1


You can base security uploads on NMUs, so I think you could get
  +deb50.1
  +deb50.1+nmu1
  +deb50.2
  +deb50.2+nmu1

        See:
 http://thread.gmane.org/gmane.linux.debian.devel.general/126121
  for more details for the reasoning behind this proposal.
---------------------------------------------------------------------

        I hope I have not missed out any common use cases which require
 special interpretations of version numbers.

        If this is acceptable, I will start trying to draft wordings for
 policy to clarify this area.

        manoj

-- System Information:
Debian Release: squeeze/sid
  APT prefers unstable
  APT policy: (990, 'unstable'), (500, 'oldstable'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.30.4-anzu (SMP w/2 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) (ignored: LC_ALL set to en_US.UTF-8)
Shell: /bin/sh linked to /bin/bash

debian-policy depends on no packages.

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base                      0.9.3      utilities to manage online documen

-- no debconf information

-- 
"Irrationality is the square root of all evil" Douglas Hofstadter
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/~srivasta/>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C


Reply to: