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
From 968690ca65c7510e0fb2e6170e914c4d1b34e456 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=UTF-8 Content-Transfer-Encoding: 8bit Based on text and ideas from Charles Plessy, Joe Nahmias, Bill Allombert, Otto Kekäläinen, Osamu Aoki. --- 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 --- a/copyright-format-1.0.xml +++ b/copyright-format-1.0.xml @@ -246,6 +246,11 @@ <link linkend="copyright-field">Copyright</link>: optional. </para> </listitem> + <listitem> + <para> + <link linkend="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> + <section id="files-excluded-included-field"> + <title><varname>Files-Excluded, Files-Excluded-*, Files-Included, Files-Included-*</varname></title> + <para> + <link linkend="white-space-lists"> + Whitespace‑separated filename patterns</link>, as in the + <link linkend="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‑Excluded + lists patterns for files or directories to + omit. Files‑Included lists patterns for files that should + not be omitted even if they match a Files‑Excluded rule. For + multi‑orig.tar sources, Files‑Excluded‑COMPONENT and + Files‑Included‑COMPONENT 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="license-field"> <title><varname>License</varname></title> <para> -- 2.54.0
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‑separated filename patterns, as in the Files field, used to > indicate which parts of the upstream source specified in the Source > field will not be included in the Debian source package. Files‑Excluded > lists patterns for files or directories to omit. Files‑Included lists > patterns for files that should not be omitted even if they match a > Files‑Excluded rule. For multi‑orig.tar sources, Files‑Excluded‑COMPONENT > and Files‑Included‑COMPONENT 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. > ---------------------------------------------------------------- > > Have a nice day, > > Charles >
signature.asc
Description: PGP signature
