Bug#1131015: mention Files-Excluded/Included-* in copyright-format-1.0.xml

--==-=-=
Content-Type: multipart/mixed; boundary="=-=-="

--=-=-=
Content-Type: text/plain

Thanks for going through earlier discussions Charles!  Please find
attached an updated patch, using your proposed paragraph but adding a
parenthesis about wildcards/directory names which I find clarifying.

What do you all think about this self-contained patch?

/Simon

--=-=-=
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: inline;
 filename=0001-Mention-Files-Excluded-Included-in-copyright-format.patch
Content-Transfer-Encoding: quoted-printable

From=20968690ca65c7510e0fb2e6170e914c4d1b34e456 Mon Sep 17 00:00:00 2001
From: Simon Josefsson <[email protected]>
Date: Mon, 16 Mar 2026 11:01:42 +0100
Subject: [PATCH] Mention Files-Excluded/Included in copyright-format
MIME-Version: 1.0
Content-Type: text/plain; charset=3DUTF-8
Content-Transfer-Encoding: 8bit

Based on text and ideas from Charles Plessy, Joe Nahmias, Bill
Allombert, Otto Kek=C3=A4l=C3=A4inen, Osamu Aoki.
=2D--
 copyright-format-1.0.xml | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index 954a65b..a5a7aa0 100644
=2D-- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -246,6 +246,11 @@
             <link linkend=3D"copyright-field">Copyright</link>: optional.
           </para>
         </listitem>
+        <listitem>
+          <para>
+            <link linkend=3D"files-excluded-included-field">Files-Excluded=
, Files-Excluded-*, Files-Included, Files-Included-*</link>: optional.
+          </para>
+        </listitem>
       </itemizedlist>
       <para>
         The <varname>Copyright</varname> and <varname>License</varname>
@@ -498,6 +503,27 @@ License: MPL-1.1
       </para>
     </section>
=20
+    <section id=3D"files-excluded-included-field">
+      <title><varname>Files-Excluded, Files-Excluded-*, Files-Included, Fi=
les-Included-*</varname></title>
+      <para>
+        <link linkend=3D"white-space-lists">
+	  Whitespace=E2=80=91separated filename patterns</link>, as in the
+	  <link linkend=3D"files-field">Files</link> field (including
+	  wildcards and directory names), used to indicate which parts
+	  of the upstream source specified in the Source field will
+	  not be included in the Debian source package. Files=E2=80=91Excluded
+	  lists patterns for files or directories to
+	  omit. Files=E2=80=91Included lists patterns for files that should
+	  not be omitted even if they match a Files=E2=80=91Excluded rule. For
+	  multi=E2=80=91orig.tar sources, Files=E2=80=91Excluded=E2=80=91COMPONEN=
T and
+	  Files=E2=80=91Included=E2=80=91COMPONENT apply the same logic but only =
to
+	  the specified orig.tar component. These fields may also be
+	  used by maintainer tools to perform the exclusions, but such
+	  tools should not require the machine-readable
+	  debian/copyright file format for correct operation.
+      </para>
+    </section>
+
     <section id=3D"license-field">
       <title><varname>License</varname></title>
       <para>
=2D-=20
2.54.0


--=-=-=
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable


Charles Plessy <[email protected]> writes:

> Hello everybody,
>
> I am glad to see the documentation of Files-Excluded moving forward.
>
> In 2012 (#685506#10) I recommeded to wait and in 2013 (#685506#55) I
> wrote in a reply to Andreas:
>
>> This field was not my favorite solution to the problem, but experience
>> showed that your solution was implemented, used, and unchallenged.
>
> 13 years later, no alternative has emerged.  Moreover, Andreas made the
> important point that it is relevant to document in `debian/copyright`
> which files are removed from the upstream sources that we point to in
> the same file.
>
> In addition, `uscan` has a `--copyright` argument to use a custom
> location for the `debian/copyright` file and developers who do not wish
> to use the machine-readable copyright format can write their own package
> update scripts that take advantage of this option.  In the context of
> creating new packages I have used `uscan` with a short machine-readable
> copyright file header stub without `Files` paragraphs, and it works
> well.  Thus, there is no obligation to use the machine-readable format
> to document the package copyright in order to be able to use `uscan`'s
> facility for removing files from tarballs.
>
> I have read the whole #685506, #1000771 and #1131015 again today, and my
> main recommendation would be to also credit Joe Nahmias for their patch
> in #685506#197, which is not directly here used but primed some of the
> stakeholders here for their review of the current patch.
>
> I have read the plain text rendering of 1131015#75 as well as uscan(1),
> https://wiki.debian.org/UscanEnhancements; altogether this matches my
> understanding and the experience I have with the tool, with the caveat
> that I never used the Files-Excluded-<component> syntax.
>
> Finally, in addition to be used by `uscan` and `mk-origtargz`, the
> `Files-Excluded` is also recognised by multiple tools such as `cme` and
> `lintian` for instance.  I do not think it needs to be documented but I
> mention it to illustrate how the field has spread in our ecosystem in
> the past 14 years or so.
>
> Based on Simon's patch, and following Osamu's recommendation in
> #1000771#15 to keep things short, and Bill's concerns about tying
> maintainer tools to a particular format of the `debian/copyright` file,
> I would like to propose the following modified text.
>
> ----------------------------------------------------------------
> Whitespace=E2=80=91separated filename patterns, as in the Files field, us=
ed to
> indicate which parts of the upstream source specified in the Source
> field will not be included in the Debian source package. Files=E2=80=91Ex=
cluded
> lists patterns for files or directories to omit. Files=E2=80=91Included l=
ists
> patterns for files that should not be omitted even if they match a
> Files=E2=80=91Excluded rule. For multi=E2=80=91orig.tar sources, Files=E2=
=80=91Excluded=E2=80=91COMPONENT
> and Files=E2=80=91Included=E2=80=91COMPONENT apply the same logic but onl=
y to the
> specified orig.tar component. These fields may also be used by
> maintainer tools to perform the exclusions, but such tools should not
> require the machine-readable debian/copyright file format for correct
> operation.
> ----------------------------------------------------------------
>
> Have a nice day,
>
> Charles
>

--=-=-=--

--==-=-=
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQNoBAEWCgMQFiEEo8ychwudMQq61M8vUXIrCP5HRaIFAmoZNwcUHHNpbW9uQGpv
c2Vmc3Nvbi5vcmfCHCYAmDMEXJLOtBYJKwYBBAHaRw8BAQdACIcrZIvhrxDBkK9f
V+QlTmXxo2naObDuGtw58YaxlOu0JVNpbW9uIEpvc2Vmc3NvbiA8c2ltb25Aam9z
ZWZzc29uLm9yZz6IlgQTFggAPgIbAwULCQgHAgYVCAkKCwIEFgIDAQIeAQIXgBYh
BLHSvRN1vst4TPT4xNc89jjFPAa+BQJp4fWRBQkOa+rdAAoJENc89jjFPAa+hWIA
/1lQvrJeGlQq50lP6tm99D1zDy7J1tQ3ha4x0Jx7rkFTAP9hpUKuTvm6m1fXyiZV
YZlu2+Id/Dq3CIAZvNF+XEr2BLgzBFySz4EWCSsGAQQB2kcPAQEHQOxTCIOaeXAx
I2hIX4HK9bQTpNVei708oNr1Klm8qCGKiPUEGBYIACYCGwIWIQSx0r0Tdb7LeEz0
+MTXPPY4xTwGvgUCaeCW1wUJDmqLVgCBdiAEGRYIAB0WIQSjzJyHC50xCrrUzy9R
cisI/kdFogUCXJLPgQAKCRBRcisI/kdFoqdMAQCgH45aseZgIrwKOvUOA9QfsmeE
8GZHYNuFHmM9FEQS6AD6A4x5aYvoY6lo98pgtw2HPDhmcCXFItjXCrV4A0GmJA4J
ENc89jjFPAa+s7AA+gIIHpBApDpcDj1sKhzDngmpvwQf0VkHme6s+EG7qSgpAQDe
/XMrU0c0Pa3ji85cMqZhvzJOFI/soe662lzL0QY3Bbg4BFySz2oSCisGAQQBl1UB
BQEBB0AxlRumDW6nZY7A+VCfek9VpEx6PJmdJyYPt3lNHMd6HAMBCAeIfgQYFggA
JgIbDBYhBLHSvRN1vst4TPT4xNc89jjFPAa+BQJp4JbXBQkOaottAAoJENc89jjF
PAa+RNUA/2faQO/nFT06E+MlhlQdo/0chlQXC5TZMPTVvVBFwoLOAP9xLJK0ow5E
jTzYJB4K810AL/Iv6PEOAEgA4cPTHVlbCQAKCRBRcisI/kdFopRaAQCcOJru8oFi
YrxJdWLWNh7KM5jlGMEm6VfN+sCjmjHGeAEA+8sIkKMwwjsHJn4fPnus6BVRk8HB
M/6u9VfUErWebgU=
=ojF1
-----END PGP SIGNATURE-----
--==-=-=--