Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.bugs.dist > #1265175 > unrolled thread

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

Back to article view | Back to linux.debian.bugs.dist

Contents

  Bug#1117566: debian-policy: Unclear wording of user-defined control fields Richard Hansen <rhansen@rhansen.org> - 2025-10-08 02:50 +0200
    Bug#1117566: debian-policy: Unclear wording of user-defined control fields Sean Whitton <spwhitton@spwhitton.name> - 2025-10-09 14:50 +0200
    Bug#1117566: debian-policy: Unclear wording of user-defined control fields Guillem Jover <guillem@debian.org> - 2025-10-09 22:50 +0200

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

[Multipart message — attachments visible in raw view] — view raw

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.

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.

[toc] | [next] | [standalone]

#1265377

[Multipart message — attachments visible in raw view] — view raw

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.

-- 
Sean Whitton

[toc] | [prev] | [next] | [standalone]

#1265431

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.bugs.dist

csiph-web