Guillem Jover <guil...@debian.org> 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) <https://www.eyrie.org/~eagle/>
>From 516d0a327e247c35bd1bb95ff2a9bfc773f87c21 Mon Sep 17 00:00:00 2001 From: Russ Allbery <r...@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 | 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 <s-f-Source>` (mandatory) -- :ref:`Binary <s-f-Binary>` (mandatory) +- :ref:`Binary <s-f-Binary>` (mandatory in some cases) - :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>` (mandatory in some cases) - :ref:`Closes <s-f-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
