Bug#1117566: debian-policy: Unclear wording of user-defined control fields

[Guillem Jover <guillem@debian.org>]

Hi!

On Tue, 2025-10-07 at 20:37:12 -0400, Richard Hansen wrote:
> Source: debian-policy
> Version: 4.7.2.0
> Severity: normal
> Tags: patch
> X-Debbugs-Cc: debian-go@lists.debian.org

> Section 5.7 "User-defined fields" has unclear wording that makes it
> difficult to understand what is and is not supported.  Specifically:
> 
>   * It does not say whether different binary packages built by the
> same source package can have different values of a custom field.
>   * It is unclear whether user-defined fields in a binary package
> stanza is supported.
>   * It does not say what happens if the same field is specified
> multiple times.
>   * It does not say what happens if the field collides with another
> field.  For example:
> 
>         Source: foo
>         XS-Source: bar
> 
> The deb-src-control(5) man page is similarly unclear, but it does
> provide an example showing a XB-* user-defined field in a binary
> package stanza.

Ah, nice catch! I agree this is all not very clearly specified or
documented.

> I manually tested dpkg-buildpackage with a debian/control containing:
> 
>     Source: foo
>     XSCB-Foo: default
>     # ...
> 
>     Package: foo-a
>     XSC-Foo: note the missing B
>     # ...
> 
>     Package: foo-b
>     XB-Foo: overridden
>     # ...
> 
> and observed the following behavior:
> 
>   * The foo-a package contained "Foo: default", as expected.
>   * The foo-b package contained "Foo: overridden", as expected.
>   * The *.dsc file contained "Foo: note the missing B".  (This was a
> bit surprising to me, as I expected S- and C-type fields to only be
> valid in the source package stanza.)
>   * The *.changes file contained "Foo: note the missing B", which is
> consistent with the *.dsc, as expected.

Thanks for looking into it and digging into the current behavior. I
just wanted to send a brief not that when I read this report, and the
proposed wording patch I also wondered that several of the cases
presented (such as XS- or XC- in binary stanzas) didn't make much
apparent sense, and was considering that some cases should be
discouraged/deprecated (and warned for now and probably eventually
refused). But when digging into the code and git history, this
has been pretty much the same behavior (AFAICT) since the code
inception.

I think I could see the desire to define some fields that might appear
only once and are somehow tied to a specific binary package, where you
don't want to either move it or duplicate the field between the source
and binary stanzas. But otherwise because merging semantics are not
possible to implement via the user-defined fields (and that requires
proper support into the dpkg tools), this feels very awkward.

I'll sleep over this, and then try to do a more in-depth reply over
the proposal, and whether some of the current behavior should instead
be changed, and then we can discuss whether any of that makes sense
or not, etc. :)

Thanks,
Guillem