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

[Guillem Jover <guillem@debian.org>]

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 <rra@debian.org>
> 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 <s-f-Source>` (mandatory)
>  
> --  :ref:`Binary <s-f-Binary>` (mandatory)
> +-  :ref:`Binary <s-f-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 <s-f-Architecture>` (mandatory)
>  
> @@ -292,7 +292,7 @@ The fields in this file are:
>  
>  -  :ref:`Changed-By <s-f-Changed-By>`
>  
> --  :ref:`Description <s-f-Description>` (mandatory)
> +-  :ref:`Description <s-f-Description>`
>  
>  -  :ref:`Closes <s-f-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