Bug#1132656: debian-policy: [multiarch] Please document dependency architecture qualifiers: foo:any, bar:native, baz:i386

Package: debian-policy
Version: 4.7.4.1
Severity: wishlist
X-Debbugs-Cc: [email protected], [email protected], [email protected]

Policy now documents the Multi-Arch field (#749826), and as part of 
that it has a brief mention in §5.6.34.4 "Multi-Arch: allowed" of how the 
:any suffix on dependencies works. (Briefly: if foo is Multi-Arch: 
allowed, then a dependency on foo is treated as though foo was 
Multi-Arch: no, but a dependency on foo:any treats it as though foo was 
Multi-Arch: same; and if foo is *not* Multi-Arch: allowed, then a 
dependency on foo:any is unsatisfiable.)

However, §7.1 "Syntax of relationship fields" doesn't currently document 
the syntax of architecture qualifiers (foo:any, bar:native, baz:i386), 
only architecture restrictions (foo [i386], bar [linux-any]) and profile 
restrictions (foo <!nodoc>, bar <cross>).

I think a new section 7.1.2 alongside 7.1.1 "Restrictions" would 
probably be the best place for this? A minimal version would be to 
mention that the foo:bar syntax is allowed, is called an "architecture 
qualifier", and dpkg defines the possible values of bar and their 
meanings; but it would probably be better if Policy was the canonical 
reference for the possible values, since dpkg, apt, sbuild, etc. all 
need to agree on what they mean.

dpkg documents architecture qualifiers in its man pages, which could be 
used as a basis for this.

deb-control(5) documents this for binary packages' dependency fields 
(Depends, Recommends etc.): a "real Debian architecture name" can appear 
after the colon, and as a special case, foo:any is also allowed. I'm not 
100% sure what "real" means in this context: probably the intention is 
that a specific, concrete architecture name like foo:i386 is considered 
to be "real", but a wildcard like foo:any-i386 or foo:linux-any is not?

deb-src-control(5) documents the same architecture qualifiers for 
Build-Depends etc. as for Depends, plus a second special case, 
foo:native, which is described as "will match the current build 
architecture if the package is not marked with Multi-Arch: foreign." I'm 
not 100% sure whether this means that a B-D on something like 
bash:native will be treated as an unsatisfiable build-dependency in the 
case where bash *is* M-A: foreign (as in fact it is), or whether a B-D 
on bash:native is merely equivalent to a B-D on bash in that case. I 
would hope it's the latter - that seems like it would have more useful 
semantics, especially when packages were not initially marked 
Multi-Arch: foreign but could/should have been.

    smcv