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.

The lack of clarity has resulted in at least one Go team bug due to a
suboptimal tooling design (involving the XS-Go-Import-Path field); see:

https://salsa.debian.org/go-team/go-team.pages.debian.net/-/merge_requests/11
https://lists.debian.org/debian-go/2025/10/msg00033.html
https://lists.debian.org/debian-go/2025/10/msg00034.html
https://salsa.debian.org/go-team/packages/golang-github-coreos-go-oidc-v3/-/merge_requests/1

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.

Attached is a proposed wording change.

Hello Richard,

Thanks.  Before codifying this in Policy it seems worth checking with
the dpkg maintainers that all the dpkg behaviour is as intended, and
fixing up the dpkg documentation.  This might reveal some rationales for
some of the more surprising behaviours, and also might eliminate the
remaining undefined behaviours.

Then Policy could include a shorter description, that wasn't just a
statement of observed behaviours, but also an explanation of why the
mechanism is the way it is.

Hi!

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

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

Hi!

I went with starting a deprecation process for the export markers that
make no sense in the binary context, with dpkg commit:

https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=b7334ac2ba0d3b189add4e5036e614c05d5e02ec

which is part of dpkg 1.23.0.

Thanks,
Guillem