Merge branch 'next'

6 files changed, 131 insertions, 37 deletions

diff --git a/debian/changelog b/debian/changelog
index 8e6b143..04b418d 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,28 @@
-debian-policy (4.3.0.4) UNRELEASED; urgency=medium
+debian-policy (4.4.0.0) UNRELEASED; urgency=medium
 
-  [ Sean Whitton]
+  [ Sean Whitton ]
+  * Policy: Recommend use of dh
+    Wording: Russ Allbery <rra@debian.org>
+    Wording: Sean Whitton <spwhitton@spwhitton.name>
+    Seconded: Sam Hartman <hartmans@debian.org>
+    Closes: #930666
+  * Policy: Permit -b in Vcs-Hg as well as Vcs-Git
+    Wording: Chris Lamb <lamby@debian.org>
+    Seconded: Holger Levsen <holger@layer-acht.org>
+    Seconded: Sean Whitton <spwhitton@spwhitton.name>
+    Closes: #897217, #920355
+  * Policy: Document versioned Provides:
+    Wording: Dominic Hargreaves <dom@earth.li>
+    Seconded: Sean Whitton <spwhitton@spwhitton.name>
+    Seconded: gregor herrmann <gregoa@debian.org>
+    Closes: #761219
+  * virtual-package-names-list: Add logind, default-logind
+    Wording: Adam Borowski <kilobyte@angband.pl>
+    Seconded: Jonathan Nieder <jrnieder@gmail.com>
+    Seconded: Holger Levsen <holger@layer-acht.org>
+    Closes: #917431
+  * Add text to header of the virtual packages list describing the
+    "(versioned)" annotation.
   * Fix reference to FHS section in Policy 9.1.2.
     Thanks to Juuso "Linda" Lapinlampi for the patch.
   * Process: Rewrite description of 'obsolete' usertag.
@@ -14,7 +36,7 @@ debian-policy (4.3.0.4) UNRELEASED; urgency=medium
   * Fix formatting of the debian_revision explanation in Policy 5.6.12.
     Thanks to Emmanuel Arias for the patch.
 
- -- Sean Whitton <spwhitton@spwhitton.name>  Tue, 09 Apr 2019 10:20:30 -0700
+ -- Sean Whitton <spwhitton@spwhitton.name>  Wed, 13 Feb 2019 13:13:24 -0700
 
 debian-policy (4.3.0.3) unstable; urgency=medium
 
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index f6ac436..81b3542 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -973,10 +973,11 @@ repository where the Debian source package is developed.
     - Mtn (Monotone)
     - Svn (Subversion)
 
-    In the case of Git, the value consists of a URL, optionally followed
-    by the word ``-b`` and the name of a branch in the indicated
-    repository, following the syntax of the ``git clone`` command. If no
-    branch is specified, the packaging should be on the default branch.
+    In the case of Git and Mercurial, the value consists of a URL,
+    optionally followed by the word ``-b`` and the name of a branch in
+    the indicated repository, following the syntax of the ``git clone``
+    or ``hg clone`` command. If no branch is specified, the packaging
+    should be on the default branch.
 
     More than one different VCS may be specified for the same package.
 
diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 1d790e8..140fdf1 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
@@ -17,15 +17,16 @@ package names, separated by vertical bar (pipe) symbols ``|``. In such a
 case, that part of the dependency can be satisfied by any one of the
 alternative packages.  [#]_
 
-All of the fields except for ``Provides`` may restrict their
-applicability to particular versions of each named package. This is done
-in parentheses after each individual package name; the parentheses
-should contain a relation from the list below followed by a version
-number, in the format described in :ref:`s-f-Version`.
+All of the fields may restrict their applicability to particular versions
+of each named package. This is done in parentheses after each individual
+package name; the parentheses should contain a relation from the list
+below followed by a version number, in the format described in
+:ref:`s-f-Version`.
 
 The relations allowed are ``<<``, ``<=``, ``=``, ``>=`` and ``>>`` for
 strictly earlier, earlier or equal, exactly equal, later or equal and
-strictly later, respectively.  [#]_
+strictly later, respectively. The exception is the Provides field, for
+which only ``=`` is allowed.  [#]_
 
 Whitespace may appear at any point in the version specification subject
 to the rules in :ref:`s-controlsyntax`, and must appear
@@ -446,17 +447,43 @@ they can say:
 and the ``bar-plus`` package will now also satisfy the dependency for
 the ``foo`` package.
 
-If a relationship field has a version number attached, only real
-packages will be considered to see whether the relationship is satisfied
-(or the prohibition violated, for a conflict or breakage). In other
-words, if a version number is specified, this is a request to ignore all
-``Provides`` for that package name and consider only real packages. The
-package manager will assume that a package providing that virtual
-package is not of the "right" version. A ``Provides`` field may not
-contain version numbers, and the version number of the concrete package
-which provides a particular virtual package will not be considered when
-considering a dependency on or conflict with the virtual package name.
-[#]_
+A ``Provides`` field may contain version numbers, and such a version number
+will be considered when considering a dependency on or conflict with the
+virtual package name.  For example, given the following packages:
+
+::
+
+    Package: foo
+    Depends: bar (>= 1.0)
+
+    Package: bar
+    Version: 0.9
+
+    Package: bar-plus
+    Provides: bar (= 1.0)
+
+the ``bar-plus`` package will satisfy the dependency for the ``foo``
+package with the virtual package name, as above.  If the ``Provides``
+field does not specify a version number, it will not satisfy versioned
+dependencies or violate versioned ``Conflicts`` or ``Breaks``. For example,
+given the following packages:
+
+::
+
+    Package: foo
+    Depends: bar (>= 1.0)
+
+    Package: bar
+    Version: 0.9
+
+    Package: bar-plus
+    Provides: bar (= 1.0)
+
+    Package: bar-clone
+    Provides: bar
+
+the ``bar-plus`` package will satisfy the dependency for the ``foo``
+package, but the ``bar-clone`` package will not.
 
 To specify which of a set of real packages should be the default to
 satisfy a particular dependency on a virtual package, list the real
@@ -670,12 +697,6 @@ dependencies.
    together and then configured in their dependency order.
 
 .. [#]
-   It is possible that a future release of ``dpkg`` may add the ability
-   to specify a version number for each virtual package it provides.
-   This feature is not yet present, however, and is expected to be used
-   only infrequently.
-
-.. [#]
    To see why ``Breaks`` is normally needed in addition to ``Replaces``,
    consider the case of a file in the package foo being taken over by
    the package foo-data. ``Replaces`` will allow foo-data to be
diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index ee9270d..93beb4a 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -259,13 +259,33 @@ files, sockets or setuid or setgid files.. [#]_
 Main building script: ``debian/rules``
 --------------------------------------
 
-This file must be an executable makefile, and contains the
-package-specific recipes for compiling the package and building binary
-package(s) from the source.
-
-It must start with the line ``#!/usr/bin/make -f``, so that it can be
-invoked by saying its name rather than invoking ``make`` explicitly.
-That is, invoking either of ``make -f debian/rules args...`` or ``./debian/rules args...`` must result in identical behavior.
+This file must be an executable makefile.  It contains the
+package-specific recipes for compiling the source (if required) and
+constructing one or more binary packages.
+
+``debian/rules`` must start with the line ``#!/usr/bin/make -f``, so that
+it can be invoked by saying its name rather than invoking ``make``
+explicitly.  That is, invoking either of ``make -f debian/rules args...``
+or ``./debian/rules args...`` must result in identical behavior.
+
+The recommended way to implement the build process of a Debian package, in
+the absence of a good reason to use a different approach, is the ``dh``
+tool.  This includes the contents of the ``debian/rules`` building script.
+``dh`` is the most common packaging helper tool in Debian.  Using it will
+usually save effort in complying with the rules in this document, because
+``dh`` will automatically implement many of them without requiring
+explicit instructions.
+
+There are sometimes good reasons to use a different approach.  For
+example, the standard tools for packaging software written in some
+languages may use another tool; some rarer packaging patterns, such as
+multiple builds of the same software with different options, are easier to
+express with other tools; and a packager working on a different packaging
+helper might want to use their tool.  The recommendation to use ``dh``
+does not always apply, and use of ``dh`` is not required.
+
+For more information about how to use ``dh``, see the documentation in the
+debhelper package, most notably the dh(1) manual page.
 
 The following targets are required and must be implemented by
 ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
diff --git a/policy/upgrading-checklist.rst b/policy/upgrading-checklist.rst
index 679a187..4f8a742 100644
--- a/policy/upgrading-checklist.rst
+++ b/policy/upgrading-checklist.rst
@@ -39,6 +39,22 @@ The sections in this checklist match the values for the
 except in the two anomalous historical cases where normative
 requirements were changed in a minor patch release.
 
+Version 4.3.1
+-------------
+
+Unreleased.
+
+5.6.26
+    Permit ``-b`` in Vcs-Hg as well as Vcs-Git.
+
+7.5
+    Document versioned Provides.
+
+virtual
+    New ``logind`` and ``default-logind`` virtual packages for a package
+    providing logind API (via D-Bus and sd-login(3)), and for Debian's
+    preferred implementation, respectively.
+
 Version 4.3.0
 -------------
 
diff --git a/virtual-package-names-list.yaml b/virtual-package-names-list.yaml
index afb76a3..2a9857a 100644
--- a/virtual-package-names-list.yaml
+++ b/virtual-package-names-list.yaml
@@ -15,6 +15,14 @@
 # https://www.debian.org/doc/packaging-manuals/virtual-package-names-list.yaml
 # (or any other Debian web mirror).
 #
+# When a virtual package description says "(versioned)", it means that
+# binary packages implementing the virtual package are expected to use
+# versioned Provides: to declare the API version that is implemented.
+#
+# For example, "Provides: logind (= 123)" indicates that the package
+# provides the same D-Bus APIs that the logind included with systemd
+# version 123 provided.
+#
 # The procedure for updating the list is as follows:
 #
 # 1. Post to debian-devel saying what names you intend to use or what
@@ -110,6 +118,10 @@ virtualPackages:
    description: provides the D-Bus well-known session bus for most or all user login sessions
  - name: default-dbus-session-bus
    description: Debian's preferred implementation of dbus-session-bus, possibly architecture-specific
+ - name: logind
+   description: an org.freedesktop.login1 D-Bus API implementation (versioned)
+ - name: default-logind
+   description: Debian's preferred implementation of logind, possibly architecture-specific (versioned)
 
 # Documentation
 
@@ -443,3 +455,5 @@ virtualPackages:
 # Sean Whitton:
 #   23 Dec 2018 Added dbus-session-bus
 #               Added default-dbus-session-bus
+#   15 Feb 2019 Added logind
+#               Added default-logind