Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Russ Allbery <rra@debian.org>]

Wouter Verhelst <wouter@debian.org> writes:
> On Tue, Aug 11, 2020 at 10:05:42AM -0700, Russ Allbery wrote:
>> Wouter Verhelst <wouter@debian.org> writes:

>>> -policy: this is a question that has come up before
>>> (https://lists.debian.org/debian-devel/2016/12/msg00470.html is
>>> another example that springs to mind, but I'm pretty sure there are
>>> more), so I think we should document in Policy that a) buildd only
>>> looks at the first dependency in alternative build-dependencies, and
>>> b) why this is the case.

>> Policy already says:

>>     While Build-Depends, Build-Depends-Indep and Build-Depends-Arch
>>     permit the use of alternative dependencies, these are not normally
>>     used by the Debian autobuilders. To avoid inconsistency between
>>     repeated builds of a package, the autobuilders will default to
>>     selecting the first alternative, after reducing any
>>     architecture-specific restrictions for the build architecture in
>>     question. While this may limit the usefulness of alternatives in a
>>     single release, they can still be used to provide flexibility in
>>     building the same package across multiple distributions or
>>     releases, where a particular dependency is met by differently named
>>     packages.

>> in 7.1.  However, it's hidden in a footnote.  Perhaps we should make it
>> more prominant (and make it clear that it's normative), and tweak the
>> wording.

> Thanks, yeah, I missed that. I'll have a stab at a patch some time soon
> (probably after debconf though)

Here, a couple of years later, is a patch that does this, and which I
think is ready for seconds.

-- 
Russ Allbery (rra@debian.org)              <https://www.eyrie.org/~eagle/>

>From dd30c5455f13086dd0ef90bf6890c20729a1ac0b Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Tue, 20 Sep 2022 19:11:54 -0700
Subject: [PATCH] Improve alternative build dependency discussion

Alternatives in build dependencies are normally (except for
backports) handled specially by autobuilders to try to maintain
consistent builds.  This was documented in Policy, but in a
footnote that people often didn't see.

Move this text into the main body of the discussion of build
dependencies and reword it for additional clarity.  Add a pointer
to this discussion where alternative dependencies are introduced.
---
 policy/ch-relationships.rst | 41 ++++++++++++++++++++++---------------
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
index 5074428..f177885 100644
--- a/policy/ch-relationships.rst
+++ b/policy/ch-relationships.rst
@@ -15,7 +15,10 @@ control fields of the package, which declare dependencies on other
 packages, the package names listed may also include lists of alternative
 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.  [#]_
+alternative packages. (Alternative dependencies in ``Build-Depends``,
+``Build-Depends-Indep``, and ``Build-Depends-Arch`` are normally used in a
+restricted way. See :ref:`Relationships between source and binary packages
+<s-sourcebinarydeps>` for more details.)
 
 All of the fields may restrict their applicability to particular versions
 of each named package. This is done in parentheses after each individual
@@ -620,6 +623,27 @@ earlier for binary packages) in order to invoke the targets in
     ``Build-Conflicts-Arch`` fields must be satisfied when these targets
     are invoked.
 
+Alternative dependencies are allowed in the ``Build-Depends``,
+``Build-Depends-Indep``, and ``Build-Depends-Arch`` fields, but Debian's
+autobuilders normally interpret them in a restricted way. After
+dependencies that do not apply to the current architecture are removed,
+all alternatives specifying different package names than the first
+alternative are dropped. (Alternatives specifying the same package name
+are kept to permit relationships such as ``foo (<= x) | foo (>= y)``.)
+The effect, therefore, is to use only the first alternative that is valid
+on the relevant architecture. This is done to reduce the risk of
+inconsistencies between repeated builds.
+
+The autobuilders for the Debian backports suite do not perform this
+transformation and instead use the full alternatives list to resolve
+dependencies.
+
+While this rule for build dependencies may limit the usefulness of
+alternatives, they can still be used to provide flexibility when building
+the package outside of Debian's autobuilders, or when building it across
+multiple distributions or releases where a particular dependency is met by
+differently named packages.
+
 .. _s-built-using:
 
 Additional source packages used to build the binary - ``Built-Using``
@@ -666,21 +690,6 @@ requirements to retain the referenced source packages.  It should not
 be added solely as a way to locate packages that need to be rebuilt
 against newer versions of their build dependencies.
 
-.. [#]
-   While ``Build-Depends``, ``Build-Depends-Indep`` and
-   ``Build-Depends-Arch`` permit the use of alternative dependencies,
-   those are only used for the backports suite on the Debian autobuilders.
-   On the other suites, after reducing any architecture-specific restrictions
-   for the build architecture in question, all but the first alternative are
-   discarded except if the alternative is the same package name as the first.
-   The latter exception is useful to specify version ranges like
-   ``foo (rel x) | foo (rel y)``. This is to reduce the risk of inconsistencies
-   between repeated rebuilds.  While this may limit the usefulness of
-   alternatives in a single release, they can still be used to provide
-   flexibility in building the same package across multiple
-   distributions or releases, where a particular dependency is met by
-   differently named packages.
-
 .. [#]
    The relations ``<`` and ``>`` were previously allowed, but they were
    confusingly defined to mean earlier/later or equal rather than
-- 
2.37.2