Bug#1117566: debian-policy: Unclear wording of user-defined control fields
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.
From c35e1581ad248d985e1937cb11c05da1cac88b9d Mon Sep 17 00:00:00 2001
From: Richard Hansen <rhansen@rhansen.org>
Date: Tue, 7 Oct 2025 02:36:41 -0400
Subject: [PATCH] Clarify where user-defined fields can be specified
The previous wording could be interpreted as allowing `XB-*` fields
only in the source package stanza, not in binary package stanzas, and
did not specify what happened if the same field name appeared in both
the source package stanza and a binary package stanza.
---
policy/ch-controlfields.rst | 85 ++++++++++++++++++++++++++++++-------
1 file changed, 69 insertions(+), 16 deletions(-)
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 3d9289f..00969c7 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -1367,35 +1367,88 @@ not include this field.
User-defined fields
-------------------
-Additional user-defined fields may be added to the source package template
-control file. Such fields will be ignored, and not copied to (for
-example) binary or Debian source control files or
-Debian upload changes control files.
+Additional user-defined fields may be added to the source package
+template control file. These fields may be added to the source package
+stanza, to a binary package stanza, or to any combination of source and
+binary package stanzas. Fields with unrecognized names are ignored;
+they are not copied to (for example) binary or Debian source control
+files or Debian upload changes control files.
-If you wish to add additional unsupported fields to these output files
-you should use the mechanism described here.
+Field names that start with a prefix matching the regular expression
+``^X[SBC]*-`` (``X``, followed by zero or more of the characters ``S``,
+``B``, or ``C``, followed by the character ``-``) are used for custom
+metadata and are processed as if by following these steps:
-Fields in the source package template control file with names starting
-``X``, followed by one or more of the letters ``BCS`` and a hyphen
-``-``, will be copied to the output files. Only the part of the field
-name after the hyphen will be used in the output file. Where the letter
-``B`` is used the field will appear in binary package control files,
-where the letter ``S`` is used in Debian source control files and where
-``C`` is used in Debian upload changes control files.
+#. The field (name and value) is copied to memory.
+#. The copy is modified to remove the prefix from the field name.
+#. If the original field is part of the source package stanza:
-For example, if the source package template control file contains the
-field
+ #. The behavior is unspecified if the removed prefix:
+
+ - contains none of the characters ``S``, ``C``, or ``B``; or
+ - contains multiple copies of any character from the set ``S``,
+ ``C``, or ``B``.
+
+ #. If the removed prefix contains the character ``S``, the modified
+ copy is scheduled to be added to the Debian source control file
+ (``*.dsc``).
+ #. If the removed prefix contains the character ``C``, the modified
+ copy is scheduled to be added to the Debian upload changes control
+ file.
+ #. If the removed prefix contains the character ``B``, the modified
+ copy is scheduled to be added to every binary package's control
+ file.
+
+#. If the original field is part of a binary package stanza:
+
+ #. The behavior is unspecified if the removed prefix:
+
+ - contains the characters ``S`` or ``C``. or
+ - does not contain the character ``B``, or
+ - contains multiple copies of the character ``B``.
+
+ #. If the removed prefix contains the character ``B``, the modified
+ copy is scheduled to be added to the binary package control file
+ for that package only, replacing any same-named field (after
+ prefix removal) that might have been scheduled to be added by a
+ user-defined field from the source package stanza.
+
+#. The behavior is unspecified if:
+
+ * The modified copy is scheduled to be added to a control file and
+ the addition would result in a collision (the control file would
+ have a same-named field, even if the value is the same).
+ * The original field is not part of the source package stanza or a
+ binary package stanza.
+
+#. The modified copy is added to the control files as scheduled.
+
+For example, if the source package template control file contains:
.. code-block:: debcontrol
+ Source: example
XBS-Comment: I stand between the candle and the star.
-then the binary and Debian source control files will contain the field
+ Package: example-a
+
+ Package: example-b
+ XB-Comment: We stand between the darkness and the light.
+
+then the Debian source control file and the binary package control file
+for the ``example-a`` package will contain the field:
.. code-block:: debcontrol
Comment: I stand between the candle and the star.
+and the binary package control file for the ``example-b`` package will
+contain the field:
+
+.. code-block:: debcontrol
+
+ Comment: We stand between the darkness and the light.
+
.. _s-obsolete-control-data-fields:
Obsolete fields
--
2.51.0
Reply to: