Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Russ Allbery]

Guillem Jover  writes:

> Seconded.

Thanks!  I think the wording changes subsequent to Sam's second are
informative and within the changes the Policy Editor can make without
seconds, so I'm proceeding with this and Sam's second and have merged this
change for the next Policy release.

-- 
Russ Allbery (r...@debian.org)  

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Edward Little]

Please remove the following email address:  e.little...@gmail.com

On Sun, Sep 10, 2023 at 1:33 PM Russ Allbery  wrote:

> Here is an updated proposed change for this bug, incorporating Guillem's
> suggestions.  It is ready for seconds.
>
> --
> Russ Allbery (r...@debian.org)  
>
>

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Guillem Jover]

Hi!

On Sun, 2023-09-10 at 16:31:30 -0700, Russ Allbery wrote:
> Guillem Jover  writes:
> > Hmm, the "For this case" comes just after the "no binary packages" which
> > to me reads as being somewhat referring to it, perhaps the "no binary
> > packages" sentence should be put at the end of the paragraph to avoid
> > confusion, or the "For this case" moved instead after the "It is a
> > multiline field" one or something along those lines?
> 
> I knew I should have listened to my instincts and reworded that paragraph
> some more to make it explicit that the format of the field in the .changes
> file is different.  (Unfortunate, but oh well, too late now.)

No worries, that's what reviews are for! :D

> Here is an updated patch that restructures this paragraph to try to make
> this clearer.

Thanks, this is indeed clearer.

> >From 516d0a327e247c35bd1bb95ff2a9bfc773f87c21 Mon Sep 17 00:00:00 2001
> From: Russ Allbery 
> Date: Tue, 20 Sep 2022 21:17:55 -0700
> Subject: [PATCH] Binary and Description optional in .changes
> 
> In .changes files for source-only uploads, the Binary and
> Description fields are not present.  Document this, and be clearer
> in the description of the Description field for .changes files that
> only descriptions of binary packages are included.
> ---
>  policy/ch-controlfields.rst | 23 ++-
>  1 file changed, 14 insertions(+), 9 deletions(-)
> 
> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 4bab7df..d5c9d68 100644
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -278,7 +278,7 @@ The fields in this file are:
>  
>  -  :ref:`Source ` (mandatory)
>  
> --  :ref:`Binary ` (mandatory)
> +-  :ref:`Binary ` (mandatory in some cases)
>  
>  -  :ref:`Architecture ` (mandatory)
>  
> @@ -292,7 +292,7 @@ The fields in this file are:
>  
>  -  :ref:`Changed-By `
>  
> --  :ref:`Description ` (mandatory)
> +-  :ref:`Description ` (mandatory in some cases)
>  
>  -  :ref:`Closes `
>  
> @@ -812,12 +812,16 @@ See :ref:`s-descriptions` for further information on
>  this.
>  
>  In a ``.changes`` file, the ``Description`` field contains a summary of
> -the descriptions for the packages being uploaded. For this case, the
> -first line of the field value (the part on the same line as
> -``Description:``) is always empty. It is a multiline field, with one
> -line per package. Each line is indented by one space and contains the
> -name of a binary package, a space, a hyphen (``-``), a space, and the
> -short description line from that package.
> +the descriptions of the binary packages being uploaded. If no binary
> +packages are being uploaded, this field will not be present.
> +
> +When used inside a ``.changes`` file, the ``Description`` field has a
> +different format than in source or binary control files. It is a multiline
> +field with one line per binary package. The first line of the field value
> +(the part on the same line as ``Description:``) is always empty. Each
> +subsequent line is indented by one space and contains the name of a binary
> +package, a space, a hyphen (``-``), a space, and the short description
> +line from that package.
>  
>  .. _s-f-Distribution:
>  
> @@ -927,7 +931,8 @@ every architecture. The source control file doesn't 
> contain details of
>  which architectures are appropriate for which of the binary packages.
>  
>  When it appears in a ``.changes`` file, it lists the names of the binary
> -packages being uploaded, separated by whitespace (not commas).
> +packages being uploaded, separated by whitespace (not commas). If no
> +binary packages are being uploaded, this field will not be present.
>  
>  .. _s-f-Installed-Size:
>  

Seconded.

Thanks,
Guillem


signature.asc
Description: PGP signature

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Russ Allbery]

Guillem Jover  writes:

> Hmm, the "For this case" comes just after the "no binary packages" which
> to me reads as being somewhat referring to it, perhaps the "no binary
> packages" sentence should be put at the end of the paragraph to avoid
> confusion, or the "For this case" moved instead after the "It is a
> multiline field" one or something along those lines?

I knew I should have listened to my instincts and reworded that paragraph
some more to make it explicit that the format of the field in the .changes
file is different.  (Unfortunate, but oh well, too late now.)

Here is an updated patch that restructures this paragraph to try to make
this clearer.

-- 
Russ Allbery (r...@debian.org)  

>From 516d0a327e247c35bd1bb95ff2a9bfc773f87c21 Mon Sep 17 00:00:00 2001
From: Russ Allbery 
Date: Tue, 20 Sep 2022 21:17:55 -0700
Subject: [PATCH] Binary and Description optional in .changes

In .changes files for source-only uploads, the Binary and
Description fields are not present.  Document this, and be clearer
in the description of the Description field for .changes files that
only descriptions of binary packages are included.
---
 policy/ch-controlfields.rst | 23 ++-
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 4bab7df..d5c9d68 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -278,7 +278,7 @@ The fields in this file are:
 
 -  :ref:`Source ` (mandatory)
 
--  :ref:`Binary ` (mandatory)
+-  :ref:`Binary ` (mandatory in some cases)
 
 -  :ref:`Architecture ` (mandatory)
 
@@ -292,7 +292,7 @@ The fields in this file are:
 
 -  :ref:`Changed-By `
 
--  :ref:`Description ` (mandatory)
+-  :ref:`Description ` (mandatory in some cases)
 
 -  :ref:`Closes `
 
@@ -812,12 +812,16 @@ See :ref:`s-descriptions` for further information on
 this.
 
 In a ``.changes`` file, the ``Description`` field contains a summary of
-the descriptions for the packages being uploaded. For this case, the
-first line of the field value (the part on the same line as
-``Description:``) is always empty. It is a multiline field, with one
-line per package. Each line is indented by one space and contains the
-name of a binary package, a space, a hyphen (``-``), a space, and the
-short description line from that package.
+the descriptions of the binary packages being uploaded. If no binary
+packages are being uploaded, this field will not be present.
+
+When used inside a ``.changes`` file, the ``Description`` field has a
+different format than in source or binary control files. It is a multiline
+field with one line per binary package. The first line of the field value
+(the part on the same line as ``Description:``) is always empty. Each
+subsequent line is indented by one space and contains the name of a binary
+package, a space, a hyphen (``-``), a space, and the short description
+line from that package.
 
 .. _s-f-Distribution:
 
@@ -927,7 +931,8 @@ every architecture. The source control file doesn't contain details of
 which architectures are appropriate for which of the binary packages.
 
 When it appears in a ``.changes`` file, it lists the names of the binary
-packages being uploaded, separated by whitespace (not commas).
+packages being uploaded, separated by whitespace (not commas). If no
+binary packages are being uploaded, this field will not be present.
 
 .. _s-f-Installed-Size:
 
-- 
2.40.1

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Guillem Jover]

Hi!

On Sun, 2023-09-10 at 10:30:41 -0700, Russ Allbery wrote:
> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 4bab7df..904fa52 100644
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -812,10 +812,11 @@ See :ref:`s-descriptions` for further information on
>  this.
>  
>  In a ``.changes`` file, the ``Description`` field contains a summary of
> -the descriptions for the packages being uploaded. For this case, the
> -first line of the field value (the part on the same line as
> -``Description:``) is always empty. It is a multiline field, with one
> -line per package. Each line is indented by one space and contains the
> +the descriptions of the binary packages being uploaded. If no binary
> +packages are being uploaded, this field will not be present. For this
> +case, the first line of the field value (the part on the same line as
> +``Description:``) is always empty.

Hmm, the "For this case" comes just after the "no binary packages"
which to me reads as being somewhat referring to it, perhaps the "no
binary packages" sentence should be put at the end of the paragraph to
avoid confusion, or the "For this case" moved instead after the "It is
a multiline field" one or something along those lines?

>   It is a multiline field, with one line
> +per binary package. Each line is indented by one space and contains the
>  name of a binary package, a space, a hyphen (``-``), a space, and the
>  short description line from that package.
>  

Thanks,
Guillem

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Sam Hartman]

> "Russ" == Russ Allbery  writes:

Russ> Here is an updated proposed change for this bug, incorporating
Russ> Guillem's suggestions.  It is ready for seconds.

Russ> -- Russ Allbery (r...@debian.org)
Russ> 

I have reviewed the patch; I support the idea and second the specific
wording.


signature.asc
Description: PGP signature

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Russ Allbery]

Here is an updated proposed change for this bug, incorporating Guillem's
suggestions.  It is ready for seconds.

-- 
Russ Allbery (r...@debian.org)  

>From 66175d3775f238a5ce3a2254388ad974e81d462f Mon Sep 17 00:00:00 2001
From: Russ Allbery 
Date: Tue, 20 Sep 2022 21:17:55 -0700
Subject: [PATCH] Binary and Description optional in .changes

In .changes files for source-only uploads, the Binary and
Description fields are not present.  Document this, and be clearer
in the description of the Description field for .changes files that
only descriptions of binary packages are included.
---
 policy/ch-controlfields.rst | 16 +---
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 4bab7df..904fa52 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -278,7 +278,7 @@ The fields in this file are:
 
 -  :ref:`Source ` (mandatory)
 
--  :ref:`Binary ` (mandatory)
+-  :ref:`Binary ` (mandatory in some cases)
 
 -  :ref:`Architecture ` (mandatory)
 
@@ -292,7 +292,7 @@ The fields in this file are:
 
 -  :ref:`Changed-By `
 
--  :ref:`Description ` (mandatory)
+-  :ref:`Description ` (mandatory in some cases)
 
 -  :ref:`Closes `
 
@@ -812,10 +812,11 @@ See :ref:`s-descriptions` for further information on
 this.
 
 In a ``.changes`` file, the ``Description`` field contains a summary of
-the descriptions for the packages being uploaded. For this case, the
-first line of the field value (the part on the same line as
-``Description:``) is always empty. It is a multiline field, with one
-line per package. Each line is indented by one space and contains the
+the descriptions of the binary packages being uploaded. If no binary
+packages are being uploaded, this field will not be present. For this
+case, the first line of the field value (the part on the same line as
+``Description:``) is always empty. It is a multiline field, with one line
+per binary package. Each line is indented by one space and contains the
 name of a binary package, a space, a hyphen (``-``), a space, and the
 short description line from that package.
 
@@ -927,7 +928,8 @@ every architecture. The source control file doesn't contain details of
 which architectures are appropriate for which of the binary packages.
 
 When it appears in a ``.changes`` file, it lists the names of the binary
-packages being uploaded, separated by whitespace (not commas).
+packages being uploaded, separated by whitespace (not commas). If no
+binary packages are being uploaded, this field will not be present.
 
 .. _s-f-Installed-Size:
 
-- 
2.40.1

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Guillem Jover]

Hi!

On Tue, 2022-09-20 at 21:21:23 -0700, Russ Allbery wrote:
> Here is a patch to fix this wording in Policy.  I think it's ready for
> seconds.

> >From c98654d7effa875c6e11da16159ac3feded8f763 Mon Sep 17 00:00:00 2001
> From: Russ Allbery 
> Date: Tue, 20 Sep 2022 21:17:55 -0700
> Subject: [PATCH] Binary and Description optional in .changes
> 
> In .changes files for source-only uploads, the Binary and
> Description fields are not present.  Document this, and be clearer
> in the description of the Description field for .changes files that
> only descriptions of binary packages are included.
> ---
>  policy/ch-controlfields.rst | 20 +++-
>  1 file changed, 11 insertions(+), 9 deletions(-)
> 
> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 428b8a7..f85f75d 100644
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -278,7 +278,7 @@ The fields in this file are:
>  
>  -  :ref:`Source ` (mandatory)
>  
> --  :ref:`Binary ` (mandatory)
> +-  :ref:`Binary `

For deb-changes(5) I switched from “(required)” to “(required in
context)”, but I don't think there's any similar precedent in the
Debian policy. Just noting here mostly for reference or as possible
inspiration :), and not as any kind of blocker or conditional on
seconding.

>  
>  -  :ref:`Architecture ` (mandatory)
>  
> @@ -292,7 +292,7 @@ The fields in this file are:
>  
>  -  :ref:`Changed-By `
>  
> --  :ref:`Description ` (mandatory)
> +-  :ref:`Description `
>  
>  -  :ref:`Closes `
>  
> @@ -809,12 +809,13 @@ See :ref:`s-descriptions` for further information on
>  this.
>  
>  In a ``.changes`` file, the ``Description`` field contains a summary of
> -the descriptions for the packages being uploaded. For this case, the
> -first line of the field value (the part on the same line as
> -``Description:``) is always empty. It is a multiline field, with one
> -line per package. Each line is indented by one space and contains the
> -name of a binary package, a space, a hyphen (``-``), a space, and the
> -short description line from that package.
> +the descriptions of the binary packages being uploaded. (``.changes``
> +files for uploads containing only source packages will not have this
> +field.)

Hmm, I guess that's fine, but perhaps it would be more precise and/or
future-proof to state instead that the field is only present if there
are binary packages included (or will be missing if they are not
present, but based on the binary packages instead of the source
packages)? Things that cross my mind might be say .changes that include
only byhand entries or similar, dunno.

> […] For this case, the first line of the field value (the part on the
> +same line as ``Description:``) is always empty. It is a multiline field,
> +with one line per binary package. Each line is indented by one space and
> +contains the name of a binary package, a space, a hyphen (``-``), a space,
> +and the short description line from that package.
>  
>  .. _s-f-Distribution:
>  
> @@ -924,7 +925,8 @@ every architecture. The source control file doesn't 
> contain details of
>  which architectures are appropriate for which of the binary packages.
>  
>  When it appears in a ``.changes`` file, it lists the names of the binary
> -packages being uploaded, separated by whitespace (not commas).
> +packages being uploaded, separated by whitespace (not commas). If only
> +source packages are being uploaded, this field will not be present.

Ditto.

>  
>  .. _s-f-Installed-Size:

Thanks,
Guillem

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Sean Whitton]

Hello,

On Tue 20 Sep 2022 at 09:21PM -07, Russ Allbery wrote:

> In .changes files for source-only uploads, the Binary and
> Description fields are not present.  Document this, and be clearer
> in the description of the Description field for .changes files that
> only descriptions of binary packages are included.
> ---
>  policy/ch-controlfields.rst | 20 +++-
>  1 file changed, 11 insertions(+), 9 deletions(-)
>
> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 428b8a7..f85f75d 100644
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -278,7 +278,7 @@ The fields in this file are:
>
>  -  :ref:`Source ` (mandatory)
>
> --  :ref:`Binary ` (mandatory)
> +-  :ref:`Binary `
>
>  -  :ref:`Architecture ` (mandatory)
>
> @@ -292,7 +292,7 @@ The fields in this file are:
>
>  -  :ref:`Changed-By `
>
> --  :ref:`Description ` (mandatory)
> +-  :ref:`Description `
>
>  -  :ref:`Closes `
>
> @@ -809,12 +809,13 @@ See :ref:`s-descriptions` for further information on
>  this.
>
>  In a ``.changes`` file, the ``Description`` field contains a summary of
> -the descriptions for the packages being uploaded. For this case, the
> -first line of the field value (the part on the same line as
> -``Description:``) is always empty. It is a multiline field, with one
> -line per package. Each line is indented by one space and contains the
> -name of a binary package, a space, a hyphen (``-``), a space, and the
> -short description line from that package.
> +the descriptions of the binary packages being uploaded. (``.changes``
> +files for uploads containing only source packages will not have this
> +field.) For this case, the first line of the field value (the part on the
> +same line as ``Description:``) is always empty. It is a multiline field,
> +with one line per binary package. Each line is indented by one space and
> +contains the name of a binary package, a space, a hyphen (``-``), a space,
> +and the short description line from that package.
>
>  .. _s-f-Distribution:
>
> @@ -924,7 +925,8 @@ every architecture. The source control file doesn't 
> contain details of
>  which architectures are appropriate for which of the binary packages.
>
>  When it appears in a ``.changes`` file, it lists the names of the binary
> -packages being uploaded, separated by whitespace (not commas).
> +packages being uploaded, separated by whitespace (not commas). If only
> +source packages are being uploaded, this field will not be present.
>
>  .. _s-f-Installed-Size:

Seconded.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Russ Allbery]

Guillem Jover  writes:
> On Mon, 2020-06-22 at 18:51:21 -0700, Felix Lechner wrote:

>> Starting with an upcoming release, Lintian will check for the presence
>> of required and recommended fields in various packaging control files.
>> Our methods are probably not perfect, but it was brought to my
>> attention that 'dpkg-buildpackage -S' produces *.changes files without
>> 'Binary' and 'Description' fields.

> This is due to a fix in dpkg 1.19.3 prompted by #818618, which brought up
> an inconsistency in the handling of these fields
> (commit 4a4619831de8b8972f86b489660dc98f187cfa34 in dpkg.git). DAK got
> also fixed to accept these .changes files.

[...]

> The deb-changes(5) and policy state that these fields contain
> information for binary packages being uploaded. On a source-only upload,
> there are no such binaries, so the definition was internally
> inconsistent.  I think the only thing missing is policy clarifying that
> this field is only mandatory on non-source-only uploads.

Here is a patch to fix this wording in Policy.  I think it's ready for
seconds.

-- 
Russ Allbery (r...@debian.org)  

>From c98654d7effa875c6e11da16159ac3feded8f763 Mon Sep 17 00:00:00 2001
From: Russ Allbery 
Date: Tue, 20 Sep 2022 21:17:55 -0700
Subject: [PATCH] Binary and Description optional in .changes

In .changes files for source-only uploads, the Binary and
Description fields are not present.  Document this, and be clearer
in the description of the Description field for .changes files that
only descriptions of binary packages are included.
---
 policy/ch-controlfields.rst | 20 +++-
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 428b8a7..f85f75d 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -278,7 +278,7 @@ The fields in this file are:
 
 -  :ref:`Source ` (mandatory)
 
--  :ref:`Binary ` (mandatory)
+-  :ref:`Binary `
 
 -  :ref:`Architecture ` (mandatory)
 
@@ -292,7 +292,7 @@ The fields in this file are:
 
 -  :ref:`Changed-By `
 
--  :ref:`Description ` (mandatory)
+-  :ref:`Description `
 
 -  :ref:`Closes `
 
@@ -809,12 +809,13 @@ See :ref:`s-descriptions` for further information on
 this.
 
 In a ``.changes`` file, the ``Description`` field contains a summary of
-the descriptions for the packages being uploaded. For this case, the
-first line of the field value (the part on the same line as
-``Description:``) is always empty. It is a multiline field, with one
-line per package. Each line is indented by one space and contains the
-name of a binary package, a space, a hyphen (``-``), a space, and the
-short description line from that package.
+the descriptions of the binary packages being uploaded. (``.changes``
+files for uploads containing only source packages will not have this
+field.) For this case, the first line of the field value (the part on the
+same line as ``Description:``) is always empty. It is a multiline field,
+with one line per binary package. Each line is indented by one space and
+contains the name of a binary package, a space, a hyphen (``-``), a space,
+and the short description line from that package.
 
 .. _s-f-Distribution:
 
@@ -924,7 +925,8 @@ every architecture. The source control file doesn't contain details of
 which architectures are appropriate for which of the binary packages.
 
 When it appears in a ``.changes`` file, it lists the names of the binary
-packages being uploaded, separated by whitespace (not commas).
+packages being uploaded, separated by whitespace (not commas). If only
+source packages are being uploaded, this field will not be present.
 
 .. _s-f-Installed-Size:
 
-- 
2.37.2

Bug#963524: debian-policy: Binary and Description fields not mandatory in .changes on source-only uploads

[Guillem Jover]

Control: reassign -1 debian-policy
Control: retitle -1 debian-policy: Binary and Description fields not mandatory 
in .changes on source-only uploads

On Mon, 2020-06-22 at 18:51:21 -0700, Felix Lechner wrote:
> Package: dpkg
> Severity: normal
> X-Debbugs-CC: debian-lint-ma...@lists.debian.org

> Starting with an upcoming release, Lintian will check for the presence
> of required and recommended fields in various packaging control files.
> Our methods are probably not perfect, but it was brought to my
> attention that 'dpkg-buildpackage -S' produces *.changes files without
> 'Binary' and 'Description' fields.

This is due to a fix in dpkg 1.19.3 prompted by #818618, which brought up
an inconsistency in the handling of these fields
(commit 4a4619831de8b8972f86b489660dc98f187cfa34 in dpkg.git). DAK got
also fixed to accept these .changes files.

> Policy 5.5 states that both fields are mandatory. [1]
> 
> [1] 
> https://www.debian.org/doc/debian-policy/ch-controlfields.html#debian-changes-files-changes
> 
> You may be able to find details about an example (by building Lintian)
> at the link below.
> 
> https://salsa.debian.org/lintian/lintian/-/commit/54a3c2437eadb0684f6762a81a82163f36562d3e#note_176583
> 
> Please note that I filed this bug with normal severity, even though as
> a policy violation, it should be serious. I did so because I believe
> the policy is at least partially in error (with respect to the
> 'Binary' field).

The deb-changes(5) and policy state that these fields contain
information for binary packages being uploaded. On a source-only upload,
there are no such binaries, so the definition was internally inconsistent.
I think the only thing missing is policy clarifying that this field is only
mandatory on non-source-only uploads.

Regards,
Guillem