Remove restrictions on versioned Provides

Thanks to Simon McVittie for additional wording.

Closes: #761219

1 files changed, 46 insertions, 21 deletions

diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 1d790e8..3b68420 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 again satisfy the dependency for
+the ``foo`` package with the virtual package name.  [#]_ 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,10 +697,8 @@ 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.
+   This functionality was introduced in dpkg 1.17.11 and newer and
+   full support has been provided in the Debian archive since 2018.
 
 .. [#]
    To see why ``Breaks`` is normally needed in addition to ``Replaces``,