From d3e4bc102eb5ee935f2dd26c0fed133426a4a6da Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 15:21:37 +0200 Subject: [PATCH 01/55] Bump to 3.2 Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 32a5cc8..53d8cbc 100644 --- a/spec.md +++ b/spec.md @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: 2019 Free Software Foundation Europe e.V. # SPDX-License-Identifier: CC-BY-SA-4.0 -title: "REUSE Specification – Version 3.1" +title: "REUSE Specification – Version 3.2" --- This specification defines a standardized method for declaring copyright and From 8f7fa84cae7f776215fc5bdd8d3d96fd6259f395 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 15:34:46 +0200 Subject: [PATCH 02/55] Add Snippet as defined term Signed-off-by: Carmen Bianca BAKKER --- spec.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/spec.md b/spec.md index 53d8cbc..e884782 100644 --- a/spec.md +++ b/spec.md @@ -54,6 +54,9 @@ These are the definitions for some of the terms used in this specification: - Commentable File --- a plain text file that can contain comments. +- Snippet --- a portion of text in a Commentable File to which different + Copyright and Licensing Information applies. + - Uncommentable File --- either a plain text file that cannot contain comments or a file that is not a plain text file. @@ -104,7 +107,7 @@ associated with any Covered File, there MUST exist a License File as defined in Each Covered File MUST have Copyright and Licensing Information associated with it. There are two ways to associate Copyright and Licensing Information with a file. In addition, there is a way to associate Copyright and Licensing -Information with a snippet. +Information with a Snippet. ### Comment headers @@ -164,17 +167,18 @@ echo "SPDX-License-Identifier: MIT" > file.txt # REUSE-IgnoreEnd ``` -### In-line snippet comments +### In-line Snippet comments -If a copyright and/or licensing info is to apply only to a certain snippet -instead of the whole file, SPDX snippet tags SHOULD be used (as defined in [SPDX -Specification, Annex H](https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format)). +If some Copyright and Licensing Information is to apply only to a certain +Snippet instead of the whole Commentable File, SPDX snippet tags MUST be used +(as defined in [SPDX Specification, Annex +H](https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format)). -Such an annotated snippet block MUST start with `SPDX-SnippetBegin` to mark its -beginning and end with `SPDX-SnippetEnd` to mark the snippet's end. +Such an annotated Snippet block MUST start with `SPDX-SnippetBegin` to mark its +beginning and end with `SPDX-SnippetEnd` to mark the Snippet's end. Do note that SPDX snippet tags MUST start with `SPDX-Snippet`, meaning that the -correct copyright notice in a snippet is `SPDX-SnippetCopyrightText`. +correct copyright notice in a Snippet is `SPDX-SnippetCopyrightText`. Example: @@ -191,7 +195,7 @@ Example: Snippets may nest, and this is denoted by having `SPDX-SnippetBegin`/`SPDX-SnippetEnd` pairs within other pairs, in the same way that parentheses nest in mathematical expressions. In the case of nested -snippets, the SPDX file tags are considered to apply to the inner-most snippet. +Snippets, the SPDX snippet tags are considered to apply to the inner-most Snippet. ### DEP5 From e7e6051e7e17d898c7a76294daca83058aaed6c5 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 15:45:49 +0200 Subject: [PATCH 03/55] Reformat section Signed-off-by: Carmen Bianca BAKKER --- spec.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index e884782..1835b25 100644 --- a/spec.md +++ b/spec.md @@ -98,9 +98,10 @@ Everything that applies to licenses in this section also applies to license exceptions, with the exception that it is NOT possible to have a license exception that does not exist in the SPDX License List. -For avoidance of doubt, in practice this means that for every license and exception -that is part of any SPDX License Expression in any Copyright and Licensing Information -associated with any Covered File, there MUST exist a License File as defined in this section. +For avoidance of doubt, in practice this means that for every license and +exception that is part of any SPDX License Expression in any Copyright and +Licensing Information associated with any Covered File, there MUST exist a +License File as defined in this section. ## Copyright and Licensing Information From 4741404af9f0116dfa9f7891962141d8c93e075e Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 15:53:20 +0200 Subject: [PATCH 04/55] Improve wording of paragraph Signed-off-by: Carmen Bianca BAKKER --- spec.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index 1835b25..d1d6c07 100644 --- a/spec.md +++ b/spec.md @@ -149,11 +149,11 @@ An example of a comment header: ``` If these tags are additionally used in the file without describing the file's -actual license or copyright but for example as part of an output command or -documentation, these occurrences MAY be put between two comments: -`REUSE-IgnoreStart` and `REUSE-IgnoreEnd`. The REUSE Tool then ignores all tags -within. This technique MUST NOT be used to ignore valid tags for licensing or -copyright. +actual license or copyright (for example: as part of an output command or +documentation), these occurrences SHOULD be put between two comments: +`REUSE-IgnoreStart` and `REUSE-IgnoreEnd`. The REUSE Tool then ignores all +Copyright and Licensing Information between these comments. This technique MUST +NOT be used to ignore valid Copyright and Licensing Information. An example for an ignored block: From d547fb0c37c83c1c4d13bfa9d5c17edb1f3d84d3 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 16:15:20 +0200 Subject: [PATCH 05/55] Improve definition of Copyright Notices Signed-off-by: Carmen Bianca BAKKER --- spec.md | 53 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/spec.md b/spec.md index d1d6c07..011e22d 100644 --- a/spec.md +++ b/spec.md @@ -35,6 +35,9 @@ These are the definitions for some of the terms used in this specification: copyright holders of a file or work, and describes under which licenses the file or work is made available. +- Copyright Notice --- a line of text that conveys copyright of a copyright + holder. + - Covered File --- any file in a Project, except for - The License Files. - The files belonging to the Project's version control system (example: @@ -117,21 +120,16 @@ contain comments at the top of the file (comment header) that declare that file's Copyright and Licensing Information. For Uncommentable Files, the comment header that declares the file's Copyright -and Licensing Information SHOULD be in an adjacent UTF-8 encoded text file of the same +and Licensing Information MUST be in an adjacent UTF-8 encoded text file of the same name with the additional extension `.license` (example: `cat.jpg.license` if the original file is `cat.jpg`). `.license` files MAY be used with Commentable Files, but it is still RECOMMENDED that comment headers be put inside Commentable Files. -The comment header MUST contain one or more `SPDX-FileCopyrightText` tags, and one or -more `SPDX-License-Identifier` tags. A tag is followed by a colon, followed by -a text value, and terminated by a newline. - -The `SPDX-FileCopyrightText` tag MUST be followed by a copyright notice. - -Instead of the `SPDX-FileCopyrightText` tag, the symbol `©`, or the word `Copyright` MAY -be used, in which case a colon is not needed. +The comment header MUST contain one or more Copyright Notices and one or more +`SPDX-License-Identifier` tag-value pairs. A tag is followed by a colon, +followed by a text value, and terminated by a newline. The `SPDX-License-Identifier` tag MUST be followed by a valid SPDX License Expression describing the licensing of the file (example: @@ -143,7 +141,7 @@ An example of a comment header: ``` # SPDX-FileCopyrightText: 2016, 2018-2019 Jane Doe -# SPDX-FileCopyrightText: 2019 Example Company +# SPDX-FileCopyrightText: 2019 Example NGO # # SPDX-License-Identifier: GPL-3.0-or-later ``` @@ -179,7 +177,7 @@ Such an annotated Snippet block MUST start with `SPDX-SnippetBegin` to mark its beginning and end with `SPDX-SnippetEnd` to mark the Snippet's end. Do note that SPDX snippet tags MUST start with `SPDX-Snippet`, meaning that the -correct copyright notice in a Snippet is `SPDX-SnippetCopyrightText`. +correct SPDX copyright tag in a Snippet is `SPDX-SnippetCopyrightText`. Example: @@ -211,7 +209,8 @@ root of the Project (i.e. `.reuse/dep5`). The `License` tag MUST be followed by a valid SPDX License Expression describing the licensing of the associated files. -The `Copyright` tag MUST be followed by a copyright notice. +The `Copyright` tag MUST be followed by a Copyright Notice. The prefix of the +Copyright Notice MAY be omitted. An example of a DEP5 file: @@ -238,12 +237,21 @@ following order of precedence: There is no merging of information from different sources. Only the source with the highest precedence is considered. -## Format of copyright notices +## Format of Copyright Notices + +A Copyright Notice MUST start with a tag, word or symbol (collectively: +prefixes) from the following list: -A copyright notice MUST be prefixed by a tag, symbol or word denoting a -copyright notice as described in this specification. +- `SPDX-FileCopyrightText` (or `SPDX-SnippetCopyrightText` in Snippets) +- Copyright +- © -The copyright notice MUST contain the name of the copyright holder. The +It is RECOMMENDED to use the `SPDX-FileCopyrightText` tag. You MAY add '(C)', +'(c)' or '©' after the prefix. + +A Copyright Notice MUST be terminated by a newline. + +The Copyright Notice MUST contain the name of the copyright holder. The copyright notice SHOULD contain the year of publication and the contact address of the copyright holder. The order of these items SHOULD be: year, name, contact address. @@ -251,18 +259,21 @@ address. The year of publication MAY be a single year, multiple years, or a span of years. -The copyright holder MAY be an individual, list of individuals, group, legal -entity, or any other descriptor by which one can easily identify the -copyright holder(s). +The copyright holder SHOULD be an individual, list of individuals, group, legal +entity, or any other descriptor by which one can easily identify the copyright +holder(s). Any contact address SHOULD be in between angle brackets. -Examples of valid copyright notices: +You MAY add any further information to the Copyright Notice. + +Examples of valid Copyright Notices: ``` SPDX-FileCopyrightText: 2019 Jane Doe SPDX-FileCopyrightText: © 2019 John Doe +SPDX-SnippetCopyrightText: (C) Example Cooperative © Example Corporation Copyright 2016, 2018-2019 Joe Anybody -Copyright (c) Alice +Copyright (c) Alice, some rights reserved ``` From 2993608d306499bd900ad527c72280dce289ff93 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 16:16:40 +0200 Subject: [PATCH 06/55] Spelling Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 011e22d..5507d24 100644 --- a/spec.md +++ b/spec.md @@ -5,7 +5,7 @@ title: "REUSE Specification – Version 3.2" --- -This specification defines a standardized method for declaring copyright and +This specification defines a standardised method for declaring copyright and licensing for software projects. The goal of the specification is to have unambiguous, human- and machine-readable copyright and licensing information for each individual file in a project. Ideally this information is embedded into From 9f9ebbf242efc08bcc33d672f45e5b364771af79 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 16:25:53 +0200 Subject: [PATCH 07/55] Improve order of precedence Signed-off-by: Carmen Bianca BAKKER --- spec.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/spec.md b/spec.md index 5507d24..e39e119 100644 --- a/spec.md +++ b/spec.md @@ -227,15 +227,17 @@ License: GPL-3.0-or-later ## Order of precedence -Copyright and Licensing Information is considered according to the -following order of precedence: - -1. Information defined in the `.license` file. -2. Information defined in the Commentable File. -3. Information defined in `.reuse/dep5`. - -There is no merging of information from different sources. Only the -source with the highest precedence is considered. +If a Commentable File contains Copyright and Licensing Information but also has +an adjacent `.license` file, then the Copyright and Licensing Information +defined in the `.license` file takes precedence, and the Commentable File's +contents are ignored. + +Copyright and Licensing Information defined in `.reuse/dep5` is aggregated with +the Copyright and Licensing Information found in the Covered Files or in their +adjacent `.license` files. For clarity, this means that if the SPDX License +Expressions in a file's comment header and in the section for that file in +`.reuse/dep5` do not agree with each other, then both SPDX License Expressions +will apply to the file. ## Format of Copyright Notices From 0426d6c16e9d80649ac73d0b3f80638887bd34c5 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 16:29:52 +0200 Subject: [PATCH 08/55] Yank 3.1 in change log Signed-off-by: Carmen Bianca BAKKER --- CHANGELOG.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fbe625..ac5b29d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,16 +20,7 @@ following sections: The versions follow [semantic versioning](https://semver.org). -## Unreleased - YYYY-MM-DD - -### Changed -### Deprecated -### Removed -### Fixed -### Security -### Added - -## 3.1 - 2023-06-21 +## 3.2 - YYYY-MM-DD ### Added @@ -72,6 +63,10 @@ The versions follow [semantic versioning](https://semver.org). - Minor typos and grammar mistakes. Thanks @jlovejoy and @Jayman2000! +## 3.1 - 2023-06-21 [YANKED] + +This version was yanked soon after release after a new definition of the order +of precedence broke compatibility. ## 3.0 - 2019-08-07 From 779c2f7b2f73ff216027997d6328d4742a36e7dc Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 17 Oct 2023 16:43:05 +0200 Subject: [PATCH 09/55] Adjust and add change log entries Signed-off-by: Carmen Bianca BAKKER --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ac5b29d..4976a43 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,7 +50,7 @@ The versions follow [semantic versioning](https://semver.org). - URLs to currently applicable SPDX specification. (#49) -- Define current order or precedence. (#131) +- Define an order or precedence. (formerly #131, overhauled in #133) ### Changed @@ -63,6 +63,8 @@ The versions follow [semantic versioning](https://semver.org). - Minor typos and grammar mistakes. Thanks @jlovejoy and @Jayman2000! +- Improved definition of Copyright Notices. (#133) + ## 3.1 - 2023-06-21 [YANKED] This version was yanked soon after release after a new definition of the order From 5cfce1276d45f0c1cd2075f600a66faf3a7d0178 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 24 Oct 2023 09:20:16 +0200 Subject: [PATCH 10/55] Improve Snippet section I removed some stuff that was already defined in the SPDX spec, and reworded things to be a little clearer. Signed-off-by: Carmen Bianca BAKKER --- spec.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/spec.md b/spec.md index e39e119..fc9fc91 100644 --- a/spec.md +++ b/spec.md @@ -168,34 +168,29 @@ echo "SPDX-License-Identifier: MIT" > file.txt ### In-line Snippet comments -If some Copyright and Licensing Information is to apply only to a certain -Snippet instead of the whole Commentable File, SPDX snippet tags MUST be used -(as defined in [SPDX Specification, Annex +If some Copyright and Licensing Information inside of a Commentable File is to +apply only to a certain Snippet instead of the whole file, SPDX snippet tags +MUST be used for that Snippet (as defined in [SPDX Specification, Annex H](https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format)). +This means that Copyright Notices inside of Snippets MUST be prefixed with +`SPDX-SnippetCopyrightText`. -Such an annotated Snippet block MUST start with `SPDX-SnippetBegin` to mark its -beginning and end with `SPDX-SnippetEnd` to mark the Snippet's end. +Like with comment headers, the SPDX snippet tags SHOULD be commented. -Do note that SPDX snippet tags MUST start with `SPDX-Snippet`, meaning that the -correct SPDX copyright tag in a Snippet is `SPDX-SnippetCopyrightText`. +A Snippet SHOULD contain both a Copyright Notice and an SPDX License Expression. Example: ``` # SPDX-SnippetBegin -# SPDX-License-Identifier: MIT # SPDX-SnippetCopyrightText: 2022 Jane Doe +# SPDX-License-Identifier: MIT -{$snippet_code_goes_here} +print("Hello, world!") # SPDX-SnippetEnd ``` -Snippets may nest, and this is denoted by having -`SPDX-SnippetBegin`/`SPDX-SnippetEnd` pairs within other pairs, in the same way -that parentheses nest in mathematical expressions. In the case of nested -Snippets, the SPDX snippet tags are considered to apply to the inner-most Snippet. - ### DEP5 Alternatively, Copyright and Licensing Information MAY be associated with a From 26018ffa7349be63bc164118efb48a731c916e85 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 24 Oct 2023 09:24:55 +0200 Subject: [PATCH 11/55] Add 'Contributors to project' as example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Matija Šuklje Signed-off-by: Carmen Bianca BAKKER --- spec.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec.md b/spec.md index fc9fc91..909b0de 100644 --- a/spec.md +++ b/spec.md @@ -269,6 +269,7 @@ Examples of valid Copyright Notices: ``` SPDX-FileCopyrightText: 2019 Jane Doe SPDX-FileCopyrightText: © 2019 John Doe +SPDX-FileCopyrightText: Contributors to Example Project SPDX-SnippetCopyrightText: (C) Example Cooperative © Example Corporation Copyright 2016, 2018-2019 Joe Anybody From 19aa3a13077e5d6b6cd46a570f79aa1974e87b24 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Thu, 4 Jan 2024 15:54:28 +0100 Subject: [PATCH 12/55] Add REUSE.toml Signed-off-by: Carmen Bianca BAKKER --- spec.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 89 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index 909b0de..4baf991 100644 --- a/spec.md +++ b/spec.md @@ -191,12 +191,93 @@ print("Hello, world!") # SPDX-SnippetEnd ``` -### DEP5 +### REUSE.toml -Alternatively, Copyright and Licensing Information MAY be associated with a -file through a DEP5 file. The intended use case of this method is large -directories where including a comment header in each file (or in `.license` -companion files) is impossible or undesirable. +Copyright and Licensing Information MAY be associated with a file through a +REUSE.toml file. The intended use case of this method is large directories where +including a comment header in each file (or in `.license` companion files) is +impossible or undesirable. + +A REUSE.toml file MAY be located in any directory, and can cover files that are +within its directory or deeper. You MAY have multiple REUSE.toml files in +different directories. + +The `version` key (REQUIRED) MUST have an integer value representing the schema +version of the file. This specification describes version 1 of REUSE.toml. + +Each `[[annotations]]` table represents an association of Copyright and +Licensing Information to zero or more Covered Files. It has the following keys: + +- `path` (REQUIRED), a string or list of strings of paths relative to the + REUSE.toml file's directory. Each path is a path to a Covered File with which + to associate the table's Copyright and Licensing Information. A path MAY fail + to resolve to a file in the Project. A path MAY use globbing. These are the + globbing and matching rules: + + - `*` matches everything except slashes, including `.` prefixes. + + - `**` matches everything including slashes. + + - `?` matches any single character. + + - `[seq]` matches any character in the sequence. + + - `[!seq]` matches any character not in the sequence. + + - `\` is an escape character. + + - If the path does not contain directory separators (`/`), then any file in + the REUSE.toml file's directory or subdirectories that matches the glob or + file name is matched. + +- `precedence` (OPTIONAL), a literal string. It determines the order of + precedence for Copyright and Licensing Information between the REUSE.toml file + and Covered Files in the table, and between multiple REUSE.toml files if they + both contain Information for the same Covered File. Available values are: + + - `closest`, the default value when `precedence` is not defined. This is an + instruction to use the Copyright and Licensing Information inside of the + Covered Files or their `.license` files, if available. If no such + Information is found, then the Information inside the closest REUSE.toml + that covers the File is associated. This is effectively a fallback. + + - `aggregate`. This is an instruction to always associate the Copyright and + Licensing Information defined in the table with the table's Covered Files. + Subsequently, the `closest` logic is also applied. + + - `toml`. This is an instruction to associate the Copyright and Licensing + Information defined in the table with the table's Covered Files, and to + ignore any other Information that is closer to the Files. The REUSE.toml + that is the closest to the root of the Project is authoritative. + +- `SPDX-FileCopyrightText` (REQUIRED), a string or list of strings. Each string + MUST be a Copyright Notice to be associated with the table's Covered Files. + The prefix of the Copyright Notice MAY be omitted. + +- `SPDX-License-Identifier` (REQUIRED), a string or list of strings. Each string + MUST be a valid SPDX License Expression describing the licensing of the + table's Covered Files. + +If a Covered File is covered by multiple `[[annotations]]` tables in the same +REUSE.toml file, then exclusively the last table in the file is used for that +Covered File. + +An example of a REUSE.toml file: + +```toml +version = 1 + +[[annotations]] +path = ["po/*.po", "po/*.pot"] +precedence = "aggregate" +SPDX-FileCopyrightText = "2019 Translation Company" +SPDX-License-Identifier = "GPL-3.0-or-later" +``` + +### DEP5 (Deprecated) + +Copyright and Licensing Information MAY be associated with a file through a DEP5 +file, but you SHOULD create a REUSE.toml file instead. The DEP5 file MUST be named `dep5` and stored in the `.reuse/` directory in the root of the Project (i.e. `.reuse/dep5`). @@ -234,6 +315,9 @@ Expressions in a file's comment header and in the section for that file in `.reuse/dep5` do not agree with each other, then both SPDX License Expressions will apply to the file. +The order of precedence for REUSE.toml files is described in the respective +section, and is managed using the `precedence` key. + ## Format of Copyright Notices A Copyright Notice MUST start with a tag, word or symbol (collectively: From 363300adbdee5ec0fd88c12d92e21029ab18bc8e Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Thu, 4 Jan 2024 16:49:12 +0100 Subject: [PATCH 13/55] Ignore COPYING and LICENSE See Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec.md b/spec.md index 4baf991..f1b1f48 100644 --- a/spec.md +++ b/spec.md @@ -54,6 +54,8 @@ These are the definitions for some of the terms used in this specification: Specification, Clause 4.4](https://spdx.github.io/spdx-spec/v2.3/conformance/#44-standard-data-format-requirements) (example: `sbom.spdx.json`). + - `COPYING` and `LICENSE`. These files typically contain license texts. They + are ignored by the REUSE specification for compatibility reasons. - Commentable File --- a plain text file that can contain comments. From f1fffdb1f8cbdc11311005a36df02d4927d6a87e Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Thu, 4 Jan 2024 16:49:21 +0100 Subject: [PATCH 14/55] Remove unneeded capital letter Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index f1b1f48..2ba44b0 100644 --- a/spec.md +++ b/spec.md @@ -22,7 +22,7 @@ log](https://git.fsfe.org/reuse/docs/src/branch/stable/CHANGELOG.md). These are the definitions for some of the terms used in this specification: -- REUSE Tool --- helper tool for compliance with this Specification; available +- REUSE Tool --- helper tool for compliance with this specification; available at . - Project --- any unit of content that can be associated with a distribution of From ffadfd5448bb8ee6ae5bbcacc3776a6a01994a28 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 17:27:07 +0100 Subject: [PATCH 15/55] Add extra example Signed-off-by: Carmen Bianca BAKKER --- spec.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec.md b/spec.md index 2ba44b0..13fec03 100644 --- a/spec.md +++ b/spec.md @@ -356,6 +356,7 @@ Examples of valid Copyright Notices: SPDX-FileCopyrightText: 2019 Jane Doe SPDX-FileCopyrightText: © 2019 John Doe SPDX-FileCopyrightText: Contributors to Example Project +SPDX-FileCopyrightText: 2023 Alice Hack and (other) contributors to Project X SPDX-SnippetCopyrightText: (C) Example Cooperative © Example Corporation Copyright 2016, 2018-2019 Joe Anybody From 327414a4537f545c305ad39cfcaf70f95ea24c9d Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 17:40:12 +0100 Subject: [PATCH 16/55] Clarify override of `.license` files Signed-off-by: Carmen Bianca BAKKER --- spec.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/spec.md b/spec.md index 13fec03..88a227c 100644 --- a/spec.md +++ b/spec.md @@ -239,9 +239,9 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `closest`, the default value when `precedence` is not defined. This is an instruction to use the Copyright and Licensing Information inside of the - Covered Files or their `.license` files, if available. If no such - Information is found, then the Information inside the closest REUSE.toml - that covers the File is associated. This is effectively a fallback. + Covered Files, if available. If no such Information is found, then the + Information inside the closest REUSE.toml that covers the File is + associated. This is effectively a fallback. - `aggregate`. This is an instruction to always associate the Copyright and Licensing Information defined in the table with the table's Covered Files. @@ -308,14 +308,15 @@ License: GPL-3.0-or-later If a Commentable File contains Copyright and Licensing Information but also has an adjacent `.license` file, then the Copyright and Licensing Information defined in the `.license` file takes precedence, and the Commentable File's -contents are ignored. +contents are ignored. For all intents and purposes, this counts as the +`.license` file's Copyright and Licensing Information being inside the +Commentable File. Copyright and Licensing Information defined in `.reuse/dep5` is aggregated with -the Copyright and Licensing Information found in the Covered Files or in their -adjacent `.license` files. For clarity, this means that if the SPDX License -Expressions in a file's comment header and in the section for that file in -`.reuse/dep5` do not agree with each other, then both SPDX License Expressions -will apply to the file. +the Copyright and Licensing Information found in the Covered Files. For clarity, +this means that if the SPDX License Expressions in a file's comment header and +in the section for that file in `.reuse/dep5` do not agree with each other, then +both SPDX License Expressions will apply to the file. The order of precedence for REUSE.toml files is described in the respective section, and is managed using the `precedence` key. From 27f1b16daf05a35722465495c594fbdead5eb9c9 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 17:46:25 +0100 Subject: [PATCH 17/55] Reword comment headers to correctly use MUST Signed-off-by: Carmen Bianca BAKKER --- spec.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 88a227c..0ffaa41 100644 --- a/spec.md +++ b/spec.md @@ -117,14 +117,15 @@ Information with a Snippet. ### Comment headers -To implement this method, each Commentable File SHOULD -contain comments at the top of the file (comment header) that declare that -file's Copyright and Licensing Information. +To implement this method, a Commentable File MUST declare the file's Copyright +and Licensing Information in a comment header. The Information SHOULD be as +close to the top of the top of the file as possible in a comment header. The +Commentable File SHOULD use UTF-8 encoding. For Uncommentable Files, the comment header that declares the file's Copyright -and Licensing Information MUST be in an adjacent UTF-8 encoded text file of the same -name with the additional extension `.license` (example: `cat.jpg.license` if the -original file is `cat.jpg`). +and Licensing Information MUST be in an adjacent text file of the same name with +the additional extension `.license` (example: `cat.jpg.license` if the original +file is `cat.jpg`). The adjacent file SHOULD use UTF-8 encoding. `.license` files MAY be used with Commentable Files, but it is still RECOMMENDED that comment headers be put inside Commentable Files. From f5cb72db6aead71af58cc5392680031a5d6f950e Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 17:46:54 +0100 Subject: [PATCH 18/55] Remove a superfluous text now that snippets exist The semantics of this were always rather vague anyway. The reader can read the SPDX spec instead. Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/spec.md b/spec.md index 0ffaa41..abf8d4c 100644 --- a/spec.md +++ b/spec.md @@ -136,9 +136,7 @@ followed by a text value, and terminated by a newline. The `SPDX-License-Identifier` tag MUST be followed by a valid SPDX License Expression describing the licensing of the file (example: -`SPDX-License-Identifier: GPL-3.0-or-later OR Apache-2.0`). If separate sections -of the file are licensed differently, a different `SPDX-License-Identifier` tag -MUST be included for each section. +`SPDX-License-Identifier: GPL-3.0-or-later OR Apache-2.0`). An example of a comment header: From a5675b14268d19d3f129471df0e2c15c9c5350ab Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 17:49:56 +0100 Subject: [PATCH 19/55] Added hyperlink to Format of Copyright Notices section Signed-off-by: Carmen Bianca BAKKER --- spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index abf8d4c..29c8405 100644 --- a/spec.md +++ b/spec.md @@ -36,7 +36,8 @@ These are the definitions for some of the terms used in this specification: file or work is made available. - Copyright Notice --- a line of text that conveys copyright of a copyright - holder. + holder. Its format is defined in the [Format of Copyright + Notices](#format-of-copyright-notices) section. - Covered File --- any file in a Project, except for - The License Files. From 0132b66d9067f985cfb12e9e10cb741fe12f0a03 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 17:55:21 +0100 Subject: [PATCH 20/55] Move ignore block to own section Signed-off-by: Carmen Bianca BAKKER --- spec.md | 54 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/spec.md b/spec.md index 29c8405..c39fb45 100644 --- a/spec.md +++ b/spec.md @@ -112,9 +112,15 @@ License File as defined in this section. ## Copyright and Licensing Information Each Covered File MUST have Copyright and Licensing Information associated with -it. There are two ways to associate Copyright and Licensing Information with a -file. In addition, there is a way to associate Copyright and Licensing -Information with a Snippet. +it. You can associate Copyright and Licensing Information with a file in the +following ways: + +- Comment headers +- REUSE.toml +- DEP5 + +Additionally, you can associate Copyright and Licensing Information with +Snippets inside of files. ### Comment headers @@ -148,26 +154,6 @@ An example of a comment header: # SPDX-License-Identifier: GPL-3.0-or-later ``` -If these tags are additionally used in the file without describing the file's -actual license or copyright (for example: as part of an output command or -documentation), these occurrences SHOULD be put between two comments: -`REUSE-IgnoreStart` and `REUSE-IgnoreEnd`. The REUSE Tool then ignores all -Copyright and Licensing Information between these comments. This technique MUST -NOT be used to ignore valid Copyright and Licensing Information. - -An example for an ignored block: - -``` -# SPDX-FileCopyrightText: 2021 Jane Doe -# -# SPDX-License-Identifier: GPL-3.0-or-later - -# REUSE-IgnoreStart -echo "SPDX-FileCopyrightText: $(date +'%Y') John Doe" > file.txt -echo "SPDX-License-Identifier: MIT" > file.txt -# REUSE-IgnoreEnd -``` - ### In-line Snippet comments If some Copyright and Licensing Information inside of a Commentable File is to @@ -193,6 +179,28 @@ print("Hello, world!") # SPDX-SnippetEnd ``` +### Ignore block + +If Copyright and Licensing Information is declared in a file without describing +the file's or Snippet's actual license or copyright (for example: as part of an +output command or documentation), these occurrences SHOULD be put between two +comments: `REUSE-IgnoreStart` and `REUSE-IgnoreEnd`. The REUSE Tool then ignores +all Copyright and Licensing Information between these comments. This technique +MUST NOT be used to ignore valid Copyright and Licensing Information. + +An example for an ignored block: + +``` +# SPDX-FileCopyrightText: 2021 Jane Doe +# +# SPDX-License-Identifier: GPL-3.0-or-later + +# REUSE-IgnoreStart +echo "SPDX-FileCopyrightText: $(date +'%Y') John Doe" > file.txt +echo "SPDX-License-Identifier: MIT" > file.txt +# REUSE-IgnoreEnd +``` + ### REUSE.toml Copyright and Licensing Information MAY be associated with a file through a From f7035cbd7e578568e7ef429bfab3bcf721f67a28 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 2 Feb 2024 18:21:34 +0100 Subject: [PATCH 21/55] Improve the wording for the precedence algorithms Signed-off-by: Carmen Bianca BAKKER --- spec.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index c39fb45..4b7d6be 100644 --- a/spec.md +++ b/spec.md @@ -246,10 +246,12 @@ Licensing Information to zero or more Covered Files. It has the following keys: both contain Information for the same Covered File. Available values are: - `closest`, the default value when `precedence` is not defined. This is an - instruction to use the Copyright and Licensing Information inside of the - Covered Files, if available. If no such Information is found, then the - Information inside the closest REUSE.toml that covers the File is - associated. This is effectively a fallback. + instruction to associate the Copyright and Licensing Information inside of + the Covered Files, if available. If no such Information is found, then the + Information inside the table of the closest REUSE.toml that covers the File + is associated. If a table in a closer REUSE.toml file has the `toml` + precedence for the same File, then that precedence is applied, and `closest` + is ignored. This is effectively a fallback. - `aggregate`. This is an instruction to always associate the Copyright and Licensing Information defined in the table with the table's Covered Files. @@ -257,8 +259,8 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `toml`. This is an instruction to associate the Copyright and Licensing Information defined in the table with the table's Covered Files, and to - ignore any other Information that is closer to the Files. The REUSE.toml - that is the closest to the root of the Project is authoritative. + ignore any other Information that is closer to the Files. The table in the + REUSE.toml that is the closest to the root of the Project is authoritative. - `SPDX-FileCopyrightText` (REQUIRED), a string or list of strings. Each string MUST be a Copyright Notice to be associated with the table's Covered Files. From 541c0264eb3f84b8ed82f4a5e3ea640e516324bf Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Thu, 29 Feb 2024 15:29:59 +0100 Subject: [PATCH 22/55] Add a missing word Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 4b7d6be..fe2176d 100644 --- a/spec.md +++ b/spec.md @@ -271,8 +271,8 @@ Licensing Information to zero or more Covered Files. It has the following keys: table's Covered Files. If a Covered File is covered by multiple `[[annotations]]` tables in the same -REUSE.toml file, then exclusively the last table in the file is used for that -Covered File. +REUSE.toml file, then exclusively the last matching table in the file is used +for that Covered File. An example of a REUSE.toml file: From 8a45ad49f906db48f301a415005b8956c7f24644 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 15:20:45 +0100 Subject: [PATCH 23/55] Make copyright and licensing keys optional in toml Signed-off-by: Carmen Bianca BAKKER --- spec.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index fe2176d..ef3c583 100644 --- a/spec.md +++ b/spec.md @@ -249,9 +249,10 @@ Licensing Information to zero or more Covered Files. It has the following keys: instruction to associate the Copyright and Licensing Information inside of the Covered Files, if available. If no such Information is found, then the Information inside the table of the closest REUSE.toml that covers the File - is associated. If a table in a closer REUSE.toml file has the `toml` - precedence for the same File, then that precedence is applied, and `closest` - is ignored. This is effectively a fallback. + is associated. This algorithm is applied separately for copyright and for + licensing. If a table in a closer REUSE.toml file has the `toml` precedence + for the same File, then that precedence is applied, and `closest` is + ignored. This is effectively a fallback. - `aggregate`. This is an instruction to always associate the Copyright and Licensing Information defined in the table with the table's Covered Files. @@ -262,14 +263,18 @@ Licensing Information to zero or more Covered Files. It has the following keys: ignore any other Information that is closer to the Files. The table in the REUSE.toml that is the closest to the root of the Project is authoritative. -- `SPDX-FileCopyrightText` (REQUIRED), a string or list of strings. Each string +- `SPDX-FileCopyrightText` (OPTIONAL), a string or list of strings. Each string MUST be a Copyright Notice to be associated with the table's Covered Files. The prefix of the Copyright Notice MAY be omitted. -- `SPDX-License-Identifier` (REQUIRED), a string or list of strings. Each string +- `SPDX-License-Identifier` (OPTIONAL), a string or list of strings. Each string MUST be a valid SPDX License Expression describing the licensing of the table's Covered Files. +Although the keys to associate Copyright and Licensing Information with the +Covered File are OPTIONAL, the complete Information MUST still be associated +with the File in some fashion. + If a Covered File is covered by multiple `[[annotations]]` tables in the same REUSE.toml file, then exclusively the last matching table in the file is used for that Covered File. From dd8acc229a4a5d1e79a588e771155c4339785988 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 15:29:35 +0100 Subject: [PATCH 24/55] Clarify glob matches Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index ef3c583..4e3934d 100644 --- a/spec.md +++ b/spec.md @@ -226,9 +226,9 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `*` matches everything except slashes, including `.` prefixes. - - `**` matches everything including slashes. + - `**` matches zero or more directories, including `.` prefixes. - - `?` matches any single character. + - `?` matches any single character except a slash. - `[seq]` matches any character in the sequence. From 0dc31dab00059889e5f1bcbfc9ffe16909715f55 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 15:29:58 +0100 Subject: [PATCH 25/55] REUSE.toml and DEP5 are mutually exclusive Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec.md b/spec.md index 4e3934d..c7c1fe7 100644 --- a/spec.md +++ b/spec.md @@ -119,6 +119,8 @@ following ways: - REUSE.toml - DEP5 +REUSE.toml and DEP5 are mutually exclusive. You MUST NOT use both simulaneously. + Additionally, you can associate Copyright and Licensing Information with Snippets inside of files. From 895e3a94150eee9298ca3ae55629fd5ed2fda82a Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 15:30:10 +0100 Subject: [PATCH 26/55] Do not match base name Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/spec.md b/spec.md index c7c1fe7..ab44ebe 100644 --- a/spec.md +++ b/spec.md @@ -238,10 +238,6 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `\` is an escape character. - - If the path does not contain directory separators (`/`), then any file in - the REUSE.toml file's directory or subdirectories that matches the glob or - file name is matched. - - `precedence` (OPTIONAL), a literal string. It determines the order of precedence for Copyright and Licensing Information between the REUSE.toml file and Covered Files in the table, and between multiple REUSE.toml files if they From c239896c9a9da9412ba9eaa2cbe39de6a867a19d Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 15:46:47 +0100 Subject: [PATCH 27/55] Backticks around REUSE.toml Signed-off-by: Carmen Bianca BAKKER --- spec.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/spec.md b/spec.md index ab44ebe..9d8eb6e 100644 --- a/spec.md +++ b/spec.md @@ -206,22 +206,22 @@ echo "SPDX-License-Identifier: MIT" > file.txt ### REUSE.toml Copyright and Licensing Information MAY be associated with a file through a -REUSE.toml file. The intended use case of this method is large directories where +`REUSE.toml` file. The intended use case of this method is large directories where including a comment header in each file (or in `.license` companion files) is impossible or undesirable. -A REUSE.toml file MAY be located in any directory, and can cover files that are -within its directory or deeper. You MAY have multiple REUSE.toml files in +A `REUSE.toml` file MAY be located in any directory, and can cover files that are +within its directory or deeper. You MAY have multiple `REUSE.toml` files in different directories. The `version` key (REQUIRED) MUST have an integer value representing the schema -version of the file. This specification describes version 1 of REUSE.toml. +version of the file. This specification describes version 1 of `REUSE.toml`. Each `[[annotations]]` table represents an association of Copyright and Licensing Information to zero or more Covered Files. It has the following keys: - `path` (REQUIRED), a string or list of strings of paths relative to the - REUSE.toml file's directory. Each path is a path to a Covered File with which + `REUSE.toml` file's directory. Each path is a path to a Covered File with which to associate the table's Copyright and Licensing Information. A path MAY fail to resolve to a file in the Project. A path MAY use globbing. These are the globbing and matching rules: @@ -239,16 +239,16 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `\` is an escape character. - `precedence` (OPTIONAL), a literal string. It determines the order of - precedence for Copyright and Licensing Information between the REUSE.toml file - and Covered Files in the table, and between multiple REUSE.toml files if they + precedence for Copyright and Licensing Information between the `REUSE.toml` file + and Covered Files in the table, and between multiple `REUSE.toml` files if they both contain Information for the same Covered File. Available values are: - `closest`, the default value when `precedence` is not defined. This is an instruction to associate the Copyright and Licensing Information inside of the Covered Files, if available. If no such Information is found, then the - Information inside the table of the closest REUSE.toml that covers the File + Information inside the table of the closest `REUSE.toml` that covers the File is associated. This algorithm is applied separately for copyright and for - licensing. If a table in a closer REUSE.toml file has the `toml` precedence + licensing. If a table in a closer `REUSE.toml` file has the `toml` precedence for the same File, then that precedence is applied, and `closest` is ignored. This is effectively a fallback. @@ -259,7 +259,7 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `toml`. This is an instruction to associate the Copyright and Licensing Information defined in the table with the table's Covered Files, and to ignore any other Information that is closer to the Files. The table in the - REUSE.toml that is the closest to the root of the Project is authoritative. + `REUSE.toml` that is the closest to the root of the Project is authoritative. - `SPDX-FileCopyrightText` (OPTIONAL), a string or list of strings. Each string MUST be a Copyright Notice to be associated with the table's Covered Files. @@ -274,10 +274,10 @@ Covered File are OPTIONAL, the complete Information MUST still be associated with the File in some fashion. If a Covered File is covered by multiple `[[annotations]]` tables in the same -REUSE.toml file, then exclusively the last matching table in the file is used +`REUSE.toml` file, then exclusively the last matching table in the file is used for that Covered File. -An example of a REUSE.toml file: +An example of a `REUSE.toml` file: ```toml version = 1 @@ -292,7 +292,7 @@ SPDX-License-Identifier = "GPL-3.0-or-later" ### DEP5 (Deprecated) Copyright and Licensing Information MAY be associated with a file through a DEP5 -file, but you SHOULD create a REUSE.toml file instead. +file, but you SHOULD create a `REUSE.toml` file instead. The DEP5 file MUST be named `dep5` and stored in the `.reuse/` directory in the root of the Project (i.e. `.reuse/dep5`). @@ -331,7 +331,7 @@ this means that if the SPDX License Expressions in a file's comment header and in the section for that file in `.reuse/dep5` do not agree with each other, then both SPDX License Expressions will apply to the file. -The order of precedence for REUSE.toml files is described in the respective +The order of precedence for `REUSE.toml` files is described in the respective section, and is managed using the `precedence` key. ## Format of Copyright Notices From 3e840f7357f6a5835389fb073fe29614b3f9e9fd Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 16:25:59 +0100 Subject: [PATCH 28/55] Reword path key Signed-off-by: Carmen Bianca BAKKER --- spec.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index 9d8eb6e..3338ad4 100644 --- a/spec.md +++ b/spec.md @@ -220,11 +220,10 @@ version of the file. This specification describes version 1 of `REUSE.toml`. Each `[[annotations]]` table represents an association of Copyright and Licensing Information to zero or more Covered Files. It has the following keys: -- `path` (REQUIRED), a string or list of strings of paths relative to the - `REUSE.toml` file's directory. Each path is a path to a Covered File with which - to associate the table's Copyright and Licensing Information. A path MAY fail - to resolve to a file in the Project. A path MAY use globbing. These are the - globbing and matching rules: +- `path` (REQUIRED), a string or list of strings representing paths. A path + SHOULD resolve to one or more Covered Files relative to the `REUSE.toml` + file's directory. A path MAY use globbing to match several Covered Files in a + single expression. These are the globbing and matching rules: - `*` matches everything except slashes, including `.` prefixes. From 8869ee1a58b473169cc813acbf8b1fb10d51e5f5 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Fri, 1 Mar 2024 17:08:24 +0100 Subject: [PATCH 29/55] Rename toml precedence type to override Signed-off-by: Carmen Bianca BAKKER --- spec.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/spec.md b/spec.md index 3338ad4..c8b546a 100644 --- a/spec.md +++ b/spec.md @@ -245,20 +245,21 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `closest`, the default value when `precedence` is not defined. This is an instruction to associate the Copyright and Licensing Information inside of the Covered Files, if available. If no such Information is found, then the - Information inside the table of the closest `REUSE.toml` that covers the File - is associated. This algorithm is applied separately for copyright and for - licensing. If a table in a closer `REUSE.toml` file has the `toml` precedence - for the same File, then that precedence is applied, and `closest` is - ignored. This is effectively a fallback. + Information inside the table of the closest `REUSE.toml` that covers the + File is associated. This algorithm is applied separately for copyright and + for licensing. If a table for the same File in a closer `REUSE.toml` file + has the `override` precedence, then that precedence is applied, and + `closest` is ignored. This is effectively a fallback. - `aggregate`. This is an instruction to always associate the Copyright and Licensing Information defined in the table with the table's Covered Files. Subsequently, the `closest` logic is also applied. - - `toml`. This is an instruction to associate the Copyright and Licensing + - `override`. This is an instruction to associate the Copyright and Licensing Information defined in the table with the table's Covered Files, and to ignore any other Information that is closer to the Files. The table in the - `REUSE.toml` that is the closest to the root of the Project is authoritative. + `REUSE.toml` that is the closest to the root of the Project is + authoritative. - `SPDX-FileCopyrightText` (OPTIONAL), a string or list of strings. Each string MUST be a Copyright Notice to be associated with the table's Covered Files. From 3fd4eecabd199d41437c375b7f9c0cd311f173de Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 18:00:38 +0200 Subject: [PATCH 30/55] COPYING and LICENSE can take file extensions Signed-off-by: Carmen Bianca BAKKER --- spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index c8b546a..3d6e414 100644 --- a/spec.md +++ b/spec.md @@ -55,8 +55,9 @@ These are the definitions for some of the terms used in this specification: Specification, Clause 4.4](https://spdx.github.io/spdx-spec/v2.3/conformance/#44-standard-data-format-requirements) (example: `sbom.spdx.json`). - - `COPYING` and `LICENSE`. These files typically contain license texts. They - are ignored by the REUSE specification for compatibility reasons. + - `COPYING` and `LICENSE`, with or without file extensions. These files + typically contain license texts. They are ignored by the REUSE + specification for compatibility reasons. - Commentable File --- a plain text file that can contain comments. From e6af184fec803295e82dac8da6f062c8de74430f Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 18:09:21 +0200 Subject: [PATCH 31/55] Update change log Signed-off-by: Carmen Bianca BAKKER --- CHANGELOG.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4976a43..97e190a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -51,7 +51,9 @@ The versions follow [semantic versioning](https://semver.org). - URLs to currently applicable SPDX specification. (#49) - Define an order or precedence. (formerly #131, overhauled in #133) - + +- REUSE.toml definition added. (#133) + ### Changed - Allow `.license` files for commentable files, but strongly recommend adding @@ -59,12 +61,17 @@ The versions follow [semantic versioning](https://semver.org). - Bump referenced SPDX version to 2.3, and update links. (#103) (#107) +- DEP5 deprecated. (#133) + ### Fixed - Minor typos and grammar mistakes. Thanks @jlovejoy and @Jayman2000! - Improved definition of Copyright Notices. (#133) +- `COPYING` and `LICENSE` are now marked as ignored, when they were already + ignored by the tool since its inception. (#133) + ## 3.1 - 2023-06-21 [YANKED] This version was yanked soon after release after a new definition of the order From ce294f2ef1296c7c3a724a5c2cfb7751c8376936 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 18:09:58 +0200 Subject: [PATCH 32/55] Small fixes Signed-off-by: Carmen Bianca BAKKER --- spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 3d6e414..e81ccdd 100644 --- a/spec.md +++ b/spec.md @@ -118,9 +118,10 @@ following ways: - Comment headers - REUSE.toml -- DEP5 +- DEP5 (deprecated) -REUSE.toml and DEP5 are mutually exclusive. You MUST NOT use both simulaneously. +REUSE.toml and DEP5 are mutually exclusive. You MUST NOT use both +simultaneously. Additionally, you can associate Copyright and Licensing Information with Snippets inside of files. From ce8b9804b086b84eff141e531646b40a04ebe95e Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 18:10:50 +0200 Subject: [PATCH 33/55] Remove empty lines in change log Signed-off-by: Carmen Bianca BAKKER --- CHANGELOG.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97e190a..b7c67b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,50 +25,35 @@ The versions follow [semantic versioning](https://semver.org). ### Added - Definition for Commentable and Uncommentable Files. (#123, thanks @Jayman2000) - - Introduce support of in-line snippet comments using `SPDX-SnippetBegin`/`SPDX-SnippetEnd`. (#107) - - Specify encoding of `.license` files to UTF-8. (#106, thanks @kirelagin for the helpful background information) - - Introduce `REUSE-IgnoreStart`/`REUSE-IgnoreEnd` to make the REUSE helper tool not consider the enclosed content for detecting copyright and licensing information. (#104) - - Definition for Covered File and clarify for which file copyright and licensing information is required. (#85, thanks @Jayman2000) - - Remove SPDX documents from list of Covered Files. (#103) - - Remove symlinks and zero-byte files from list of Covered Files. (#101) - - Remove submodules and Meson subprojects from list of Covered Files. (#99) - - Clarify which license text files are needed if a SPDX license expression contains more than one license and/or exception. (#96) - - URLs to currently applicable SPDX specification. (#49) - - Define an order or precedence. (formerly #131, overhauled in #133) - - REUSE.toml definition added. (#133) ### Changed - Allow `.license` files for commentable files, but strongly recommend adding copyright/licensing information in header. (#123, thanks @Jayman2000) - - Bump referenced SPDX version to 2.3, and update links. (#103) (#107) - - DEP5 deprecated. (#133) ### Fixed - Minor typos and grammar mistakes. Thanks @jlovejoy and @Jayman2000! - - Improved definition of Copyright Notices. (#133) - - `COPYING` and `LICENSE` are now marked as ignored, when they were already ignored by the tool since its inception. (#133) @@ -84,15 +69,12 @@ of precedence broke compatibility. - `SPDX-FileCopyrightText: Jane Doe` is now the recommended way to mark a copyright notice instead of `Copyright (C) Jane Doe`. `Copyright` and `©` are still supported as prefixes. - - The specification now makes a recommendation on the format of copyright notices, but does not mandate anything other than that the copyright notice contain the name of the copyright holder. The format is roughly: `SPDX-FileCopyrightText: 2019 Jane Doe ` - - An FAQ and much-needed tutorial are added to help people along, instead of letting the specification do double duty as a tutorial. - - The tool has been updated to be a lot friendlier to use, and to print more helpful linting output. In a future release it will automate some tasks (e.g., adding copyright and licensing information headers to specified files). @@ -101,9 +83,7 @@ of precedence broke compatibility. - The DEP5 file which bulk-licenses directories as a sort of global configuration file was moved from `debian/copyright` to `.reuse/dep5`. - - The three steps have been changed from - 1. Provide the exact text of each license used 2. Include a copyright notice and license in each file 3. Provide an inventory for included software @@ -119,12 +99,9 @@ of precedence broke compatibility. - The specification no longer makes a recommendation on how to deal with licenses such as BSD and MIT that themselves contain editable copyright notices. - - License files can now only be placed in `LICENSES/[spdx-identifier].[ext]` files, instead of the default `LICENSE`, `COPYING`, etc.. As a result, the `Valid-License-Identifier` tag is no longer needed. - - The specification no longer makes any mention of version control systems to track copyright. - - The specification no longer mentions a bill of materials (SPDX Document). From 1952f883d02ee17796fa73739c04764433873c1b Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 18:14:22 +0200 Subject: [PATCH 34/55] Make snippets and ignore block sections subsections of comment header Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index e81ccdd..b6a8f5d 100644 --- a/spec.md +++ b/spec.md @@ -158,7 +158,7 @@ An example of a comment header: # SPDX-License-Identifier: GPL-3.0-or-later ``` -### In-line Snippet comments +#### In-line Snippet comments If some Copyright and Licensing Information inside of a Commentable File is to apply only to a certain Snippet instead of the whole file, SPDX snippet tags @@ -183,7 +183,7 @@ print("Hello, world!") # SPDX-SnippetEnd ``` -### Ignore block +#### Ignore block If Copyright and Licensing Information is declared in a file without describing the file's or Snippet's actual license or copyright (for example: as part of an From 25e6376f82fb3c4ed580934fe7928e3afacd0616 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 18:15:50 +0200 Subject: [PATCH 35/55] Improve DEP5 example to match REUSE.toml example Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index b6a8f5d..03a8584 100644 --- a/spec.md +++ b/spec.md @@ -313,7 +313,7 @@ Upstream-Name: Project Upstream-Contact: Jane Doe Source: https://example.com/jane/project -Files: po/* +Files: po/*.po po/*.pot Copyright: 2019 Translation Company License: GPL-3.0-or-later ``` From 88b37eb35c7daa5e3a01948bee61a82258b22e30 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 19:24:51 +0200 Subject: [PATCH 36/55] Add 'comprehensive' goal to introduction blurb Signed-off-by: Carmen Bianca BAKKER --- spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec.md b/spec.md index 03a8584..860c544 100644 --- a/spec.md +++ b/spec.md @@ -7,10 +7,10 @@ title: "REUSE Specification – Version 3.2" This specification defines a standardised method for declaring copyright and licensing for software projects. The goal of the specification is to have -unambiguous, human- and machine-readable copyright and licensing information for -each individual file in a project. Ideally this information is embedded into -every file, so that the information is preserved when the file is copied and -reused by third parties. +comprehensive, unambiguous, human- and machine-readable copyright and licensing +information for each individual file in a project. Ideally this information is +embedded into every file, so that the information is preserved when the file is +copied and reused by third parties. This specification implements [IETF RFC 2119: Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119). From 00e629570acbe985d44ee11a06d9491242772d94 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sat, 27 Apr 2024 21:39:14 +0200 Subject: [PATCH 37/55] More accurate description of glob matching The 'including `.` prefixes' bit was unnecessary. Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 860c544..855039c 100644 --- a/spec.md +++ b/spec.md @@ -227,9 +227,9 @@ Licensing Information to zero or more Covered Files. It has the following keys: file's directory. A path MAY use globbing to match several Covered Files in a single expression. These are the globbing and matching rules: - - `*` matches everything except slashes, including `.` prefixes. + - `*` matches everything except slashes. - - `**` matches zero or more directories, including `.` prefixes. + - `**` matches everything including slashes. - `?` matches any single character except a slash. From 70995dd5b5da398ec6c09df55599f909d54633e9 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:34:51 +0200 Subject: [PATCH 38/55] Add unreleased section to change log --- CHANGELOG.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b7c67b9..95da1fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,22 @@ following sections: The versions follow [semantic versioning](https://semver.org). + + ## 3.2 - YYYY-MM-DD ### Added From ce8588de5bff0b0dd801d3d80244887af2baba31 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:35:26 +0200 Subject: [PATCH 39/55] Move deprecation notice to its own section in change log --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 95da1fb..966e629 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,6 +64,9 @@ The versions follow [semantic versioning](https://semver.org). - Allow `.license` files for commentable files, but strongly recommend adding copyright/licensing information in header. (#123, thanks @Jayman2000) - Bump referenced SPDX version to 2.3, and update links. (#103) (#107) + +### Deprecated + - DEP5 deprecated. (#133) ### Fixed From b0ee22aaf885ee80c56a903b362f6da4839e6c3c Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:41:15 +0200 Subject: [PATCH 40/55] Clarify COPYING and LICENSE inclusion --- spec.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index 855039c..be5f0b1 100644 --- a/spec.md +++ b/spec.md @@ -41,6 +41,7 @@ These are the definitions for some of the terms used in this specification: - Covered File --- any file in a Project, except for - The License Files. + - `COPYING` and `LICENSE`, with or without file extensions. - The files belonging to the Project's version control system (example: `.git/`). - The files ignored by the version control system (example: files listed in @@ -55,9 +56,6 @@ These are the definitions for some of the terms used in this specification: Specification, Clause 4.4](https://spdx.github.io/spdx-spec/v2.3/conformance/#44-standard-data-format-requirements) (example: `sbom.spdx.json`). - - `COPYING` and `LICENSE`, with or without file extensions. These files - typically contain license texts. They are ignored by the REUSE - specification for compatibility reasons. - Commentable File --- a plain text file that can contain comments. @@ -110,6 +108,11 @@ exception that is part of any SPDX License Expression in any Copyright and Licensing Information associated with any Covered File, there MUST exist a License File as defined in this section. +You MAY include a `COPYING` or `LICENSE` file (with or without file extensions) +in your project for compliance with other standards, conventions, or tools. +These files MAY contain a copy of the license text, a summary of your licensing, +or anything else. These files are ignored by the REUSE Tool. + ## Copyright and Licensing Information Each Covered File MUST have Copyright and Licensing Information associated with From dc41318f1c5a926040461041795ae08bd7e26028 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:43:42 +0200 Subject: [PATCH 41/55] Specify that non-license files cannot be in LICENSES/ --- spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index be5f0b1..6ba6a8b 100644 --- a/spec.md +++ b/spec.md @@ -97,7 +97,8 @@ If a license does not exist in the SPDX License List, its SPDX License Identifie MUST be `LicenseRef-[idstring]` as defined by the SPDX Specification, Clause 10 available at . A Project MUST NOT include License Files for licenses under which none of the -files in the Project are licensed. +files in the Project are licensed. The `LICENSES/` directory MUST NOT include +any other files. Everything that applies to licenses in this section also applies to license exceptions, with the exception that it is NOT possible to have a license From ce4c36a6fece1f3faa5aeb14ae0c3059a4f9b1a5 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:47:25 +0200 Subject: [PATCH 42/55] Replace NGO with Organisation --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 6ba6a8b..b6c5a56 100644 --- a/spec.md +++ b/spec.md @@ -157,7 +157,7 @@ An example of a comment header: ``` # SPDX-FileCopyrightText: 2016, 2018-2019 Jane Doe -# SPDX-FileCopyrightText: 2019 Example NGO +# SPDX-FileCopyrightText: 2019 Example Organisation # # SPDX-License-Identifier: GPL-3.0-or-later ``` From 16f0b6eb45b4604d897183597332f71c032249bc Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:48:49 +0200 Subject: [PATCH 43/55] Easier language for Snippets --- spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index b6c5a56..260b1a9 100644 --- a/spec.md +++ b/spec.md @@ -164,9 +164,9 @@ An example of a comment header: #### In-line Snippet comments -If some Copyright and Licensing Information inside of a Commentable File is to -apply only to a certain Snippet instead of the whole file, SPDX snippet tags -MUST be used for that Snippet (as defined in [SPDX Specification, Annex +Sometimes Copyright and Licensing Information only applies to a certain Snippet +instead of the whole Commentable File. For these cases SPDX snippet tags MUST be +used for that Snippet (as defined in [SPDX Specification, Annex H](https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format)). This means that Copyright Notices inside of Snippets MUST be prefixed with `SPDX-SnippetCopyrightText`. From 7eefa3cbb92d35bdecdd0c34237d0ccdf4b33180 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 11:57:26 +0200 Subject: [PATCH 44/55] Recommend comment header above all others --- spec.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/spec.md b/spec.md index 260b1a9..c1b2e9a 100644 --- a/spec.md +++ b/spec.md @@ -132,6 +132,11 @@ Snippets inside of files. ### Comment headers +Wherever possible, you SHOULD attempt to use comment headers to convey a file's +Copyright and Licensing Information. Compared to other methods, comment headers +are more explicit and their associated Information is more resistant to being +moved or copied. + To implement this method, a Commentable File MUST declare the file's Copyright and Licensing Information in a comment header. The Information SHOULD be as close to the top of the top of the file as possible in a comment header. The From 21dd034e8bd85ce0778e8df8201fcac4acb80c35 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 12:09:06 +0200 Subject: [PATCH 45/55] Allow user to include other keys and tables in TOML --- spec.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/spec.md b/spec.md index c1b2e9a..13a456c 100644 --- a/spec.md +++ b/spec.md @@ -280,6 +280,9 @@ Licensing Information to zero or more Covered Files. It has the following keys: MUST be a valid SPDX License Expression describing the licensing of the table's Covered Files. +You MAY include other keys and tables to convey additional information. Their +semantics are not defined by this specification. + Although the keys to associate Copyright and Licensing Information with the Covered File are OPTIONAL, the complete Information MUST still be associated with the File in some fashion. From 9496bdd4ab354131ada8c0bdc81edbc2ee158ef4 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 12:11:18 +0200 Subject: [PATCH 46/55] Be more explicit about path separators --- spec.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 13a456c..0527e31 100644 --- a/spec.md +++ b/spec.md @@ -231,14 +231,15 @@ version of the file. This specification describes version 1 of `REUSE.toml`. Each `[[annotations]]` table represents an association of Copyright and Licensing Information to zero or more Covered Files. It has the following keys: -- `path` (REQUIRED), a string or list of strings representing paths. A path - SHOULD resolve to one or more Covered Files relative to the `REUSE.toml` - file's directory. A path MAY use globbing to match several Covered Files in a - single expression. These are the globbing and matching rules: +- `path` (REQUIRED), a string or list of strings representing paths. A path MUST + use forward slashes as path separators. A path SHOULD resolve to one or more + Covered Files relative to the `REUSE.toml` file's directory. A path MAY use + globbing to match several Covered Files in a single expression. These are the + globbing and matching rules: - - `*` matches everything except slashes. + - `*` matches everything except forward slashes (i.e. path separators). - - `**` matches everything including slashes. + - `**` matches everything including forward slashes (i.e. path separators). - `?` matches any single character except a slash. From 1a36bd087e4dd7041fbc16cd49b5c945298cb564 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 12:14:52 +0200 Subject: [PATCH 47/55] Be more explicit about DEP5 deprecation --- spec.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 0527e31..151a487 100644 --- a/spec.md +++ b/spec.md @@ -304,10 +304,12 @@ SPDX-FileCopyrightText = "2019 Translation Company" SPDX-License-Identifier = "GPL-3.0-or-later" ``` -### DEP5 (Deprecated) +### DEP5 (deprecated) Copyright and Licensing Information MAY be associated with a file through a DEP5 -file, but you SHOULD create a `REUSE.toml` file instead. +file, but you SHOULD create a `REUSE.toml` file instead. The DEP5 file is +deprecated, meaning that it is expected to disappear from a future iteration of +this specification. The DEP5 file MUST be named `dep5` and stored in the `.reuse/` directory in the root of the Project (i.e. `.reuse/dep5`). From 2be63154e1af5eeadedad94704212903bbecd465 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 15:23:17 +0200 Subject: [PATCH 48/55] Fix John's e-mail --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 151a487..8aaa931 100644 --- a/spec.md +++ b/spec.md @@ -385,7 +385,7 @@ Examples of valid Copyright Notices: ``` SPDX-FileCopyrightText: 2019 Jane Doe -SPDX-FileCopyrightText: © 2019 John Doe +SPDX-FileCopyrightText: © 2019 John Doe SPDX-FileCopyrightText: Contributors to Example Project SPDX-FileCopyrightText: 2023 Alice Hack and (other) contributors to Project X SPDX-SnippetCopyrightText: (C) Example Cooperative From 2f7381539df75a2cfd93de3828685c5ef8d365e3 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 21:30:31 +0200 Subject: [PATCH 49/55] Simplify globbing --- spec.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/spec.md b/spec.md index 8aaa931..1ff929d 100644 --- a/spec.md +++ b/spec.md @@ -239,15 +239,13 @@ Licensing Information to zero or more Covered Files. It has the following keys: - `*` matches everything except forward slashes (i.e. path separators). - - `**` matches everything including forward slashes (i.e. path separators). + - `**` and `**/` match everything including forward slashes (i.e. path + separators). - - `?` matches any single character except a slash. - - - `[seq]` matches any character in the sequence. - - - `[!seq]` matches any character not in the sequence. - - - `\` is an escape character. + - In order to escape an asterisk and include it verbatim, prefix it with `\\`. + You cannot prefix it with `\` because that is invalid TOML. In order to + include a backslash verbatim, use `\\\\`. `\\` followed by any other + character is functionally equal to just typing that character. - `precedence` (OPTIONAL), a literal string. It determines the order of precedence for Copyright and Licensing Information between the `REUSE.toml` file From 3f8ea8f77725a34356e4ad6a1cb6d149835b8665 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Sun, 28 Apr 2024 21:31:25 +0200 Subject: [PATCH 50/55] Reduce spacing between list elements --- spec.md | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/spec.md b/spec.md index 1ff929d..8df5356 100644 --- a/spec.md +++ b/spec.md @@ -24,21 +24,16 @@ These are the definitions for some of the terms used in this specification: - REUSE Tool --- helper tool for compliance with this specification; available at . - - Project --- any unit of content that can be associated with a distribution of software. Typically, a Project is composed of one or more files. Also sometimes called a package. - - License File --- a file containing the text of a license. - - Copyright and Licensing Information --- the information that lists the copyright holders of a file or work, and describes under which licenses the file or work is made available. - - Copyright Notice --- a line of text that conveys copyright of a copyright holder. Its format is defined in the [Format of Copyright Notices](#format-of-copyright-notices) section. - - Covered File --- any file in a Project, except for - The License Files. - `COPYING` and `LICENSE`, with or without file extensions. @@ -56,27 +51,20 @@ These are the definitions for some of the terms used in this specification: Specification, Clause 4.4](https://spdx.github.io/spdx-spec/v2.3/conformance/#44-standard-data-format-requirements) (example: `sbom.spdx.json`). - - Commentable File --- a plain text file that can contain comments. - - Snippet --- a portion of text in a Commentable File to which different Copyright and Licensing Information applies. - - Uncommentable File --- either a plain text file that cannot contain comments or a file that is not a plain text file. - - SPDX Specification --- SPDX specification, version 2.3; as available on . - - SPDX License Identifier --- SPDX short-form identifier, as defined in SPDX Specification. See also for a short introduction and examples. - -- SPDX License Expression --- as defined in SPDX Specification, Annex D, at . - +- SPDX License Expression --- as defined in SPDX Specification, Annex D, at + . - SPDX License List --- a list of commonly found licenses and exceptions; as available on . - - DEP5 --- [Machine-readable `debian/copyright` file, Version 1.0](https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/). Where the REUSE Specification and DEP5 state different things, the REUSE @@ -236,22 +224,17 @@ Licensing Information to zero or more Covered Files. It has the following keys: Covered Files relative to the `REUSE.toml` file's directory. A path MAY use globbing to match several Covered Files in a single expression. These are the globbing and matching rules: - - `*` matches everything except forward slashes (i.e. path separators). - - `**` and `**/` match everything including forward slashes (i.e. path separators). - - In order to escape an asterisk and include it verbatim, prefix it with `\\`. You cannot prefix it with `\` because that is invalid TOML. In order to include a backslash verbatim, use `\\\\`. `\\` followed by any other character is functionally equal to just typing that character. - - `precedence` (OPTIONAL), a literal string. It determines the order of precedence for Copyright and Licensing Information between the `REUSE.toml` file and Covered Files in the table, and between multiple `REUSE.toml` files if they both contain Information for the same Covered File. Available values are: - - `closest`, the default value when `precedence` is not defined. This is an instruction to associate the Copyright and Licensing Information inside of the Covered Files, if available. If no such Information is found, then the @@ -260,21 +243,17 @@ Licensing Information to zero or more Covered Files. It has the following keys: for licensing. If a table for the same File in a closer `REUSE.toml` file has the `override` precedence, then that precedence is applied, and `closest` is ignored. This is effectively a fallback. - - `aggregate`. This is an instruction to always associate the Copyright and Licensing Information defined in the table with the table's Covered Files. Subsequently, the `closest` logic is also applied. - - `override`. This is an instruction to associate the Copyright and Licensing Information defined in the table with the table's Covered Files, and to ignore any other Information that is closer to the Files. The table in the `REUSE.toml` that is the closest to the root of the Project is authoritative. - - `SPDX-FileCopyrightText` (OPTIONAL), a string or list of strings. Each string MUST be a Copyright Notice to be associated with the table's Covered Files. The prefix of the Copyright Notice MAY be omitted. - - `SPDX-License-Identifier` (OPTIONAL), a string or list of strings. Each string MUST be a valid SPDX License Expression describing the licensing of the table's Covered Files. From 4e15864df5a93d833fdbdd0978c65685eda3e5e4 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 21 May 2024 10:54:26 +0200 Subject: [PATCH 51/55] Replace Copyright and Licensing Information with Licensing Information Signed-off-by: Carmen Bianca BAKKER --- spec.md | 145 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 72 insertions(+), 73 deletions(-) diff --git a/spec.md b/spec.md index 8df5356..a94e498 100644 --- a/spec.md +++ b/spec.md @@ -28,9 +28,9 @@ These are the definitions for some of the terms used in this specification: software. Typically, a Project is composed of one or more files. Also sometimes called a package. - License File --- a file containing the text of a license. -- Copyright and Licensing Information --- the information that lists the - copyright holders of a file or work, and describes under which licenses the - file or work is made available. +- Licensing Information --- the information that lists the copyright holders of + a file or work, and describes under which licenses the file or work is made + available. - Copyright Notice --- a line of text that conveys copyright of a copyright holder. Its format is defined in the [Format of Copyright Notices](#format-of-copyright-notices) section. @@ -53,7 +53,7 @@ These are the definitions for some of the terms used in this specification: (example: `sbom.spdx.json`). - Commentable File --- a plain text file that can contain comments. - Snippet --- a portion of text in a Commentable File to which different - Copyright and Licensing Information applies. + Licensing Information applies. - Uncommentable File --- either a plain text file that cannot contain comments or a file that is not a plain text file. - SPDX Specification --- SPDX specification, version 2.3; as available on @@ -76,13 +76,15 @@ These are the definitions for some of the terms used in this specification: A Project MUST include a License File for every license under which Covered Files are licensed. -Each License File MUST be placed in the `LICENSES/` directory in the root of -the Project. The name of the License File MUST be the SPDX License Identifier of the +Each License File MUST be placed in the `LICENSES/` directory in the root of the +Project. The name of the License File MUST be the SPDX License Identifier of the license followed by an appropriate file extension (example: `LICENSES/GPL-3.0-or-later.txt`). The License File MUST be in plain text format. -If a license does not exist in the SPDX License List, its SPDX License Identifier -MUST be `LicenseRef-[idstring]` as defined by the SPDX Specification, Clause 10 available at . +If a license does not exist in the SPDX License List, its SPDX License +Identifier MUST be `LicenseRef-[idstring]` as defined by the SPDX Specification, +Clause 10 available at +. A Project MUST NOT include License Files for licenses under which none of the files in the Project are licensed. The `LICENSES/` directory MUST NOT include @@ -93,20 +95,19 @@ exceptions, with the exception that it is NOT possible to have a license exception that does not exist in the SPDX License List. For avoidance of doubt, in practice this means that for every license and -exception that is part of any SPDX License Expression in any Copyright and -Licensing Information associated with any Covered File, there MUST exist a -License File as defined in this section. +exception that is part of any SPDX License Expression in any Licensing +Information associated with any Covered File, there MUST exist a License File as +defined in this section. You MAY include a `COPYING` or `LICENSE` file (with or without file extensions) in your project for compliance with other standards, conventions, or tools. These files MAY contain a copy of the license text, a summary of your licensing, or anything else. These files are ignored by the REUSE Tool. -## Copyright and Licensing Information +## Licensing Information -Each Covered File MUST have Copyright and Licensing Information associated with -it. You can associate Copyright and Licensing Information with a file in the -following ways: +Each Covered File MUST have Licensing Information associated with it. You can +associate Licensing Information with a file in the following ways: - Comment headers - REUSE.toml @@ -115,25 +116,25 @@ following ways: REUSE.toml and DEP5 are mutually exclusive. You MUST NOT use both simultaneously. -Additionally, you can associate Copyright and Licensing Information with -Snippets inside of files. +Additionally, you can associate Licensing Information with Snippets inside of +files. ### Comment headers Wherever possible, you SHOULD attempt to use comment headers to convey a file's -Copyright and Licensing Information. Compared to other methods, comment headers -are more explicit and their associated Information is more resistant to being +Licensing Information. Compared to other methods, comment headers are more +explicit and their associated Licensing Information is more resistant to being moved or copied. -To implement this method, a Commentable File MUST declare the file's Copyright -and Licensing Information in a comment header. The Information SHOULD be as -close to the top of the top of the file as possible in a comment header. The -Commentable File SHOULD use UTF-8 encoding. +To implement this method, a Commentable File MUST declare the file's Licensing +Information in a comment header. The Licensing Information SHOULD be as close to +the top of the top of the file as possible in a comment header. The Commentable +File SHOULD use UTF-8 encoding. -For Uncommentable Files, the comment header that declares the file's Copyright -and Licensing Information MUST be in an adjacent text file of the same name with -the additional extension `.license` (example: `cat.jpg.license` if the original -file is `cat.jpg`). The adjacent file SHOULD use UTF-8 encoding. +For Uncommentable Files, the comment header that declares the file's Licensing +Information MUST be in an adjacent text file of the same name with the +additional extension `.license` (example: `cat.jpg.license` if the original file +is `cat.jpg`). The adjacent file SHOULD use UTF-8 encoding. `.license` files MAY be used with Commentable Files, but it is still RECOMMENDED that comment headers be put inside Commentable Files. @@ -157,9 +158,9 @@ An example of a comment header: #### In-line Snippet comments -Sometimes Copyright and Licensing Information only applies to a certain Snippet -instead of the whole Commentable File. For these cases SPDX snippet tags MUST be -used for that Snippet (as defined in [SPDX Specification, Annex +Sometimes Licensing Information only applies to a certain Snippet instead of the +whole Commentable File. For these cases SPDX snippet tags MUST be used for that +Snippet (as defined in [SPDX Specification, Annex H](https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format)). This means that Copyright Notices inside of Snippets MUST be prefixed with `SPDX-SnippetCopyrightText`. @@ -182,12 +183,12 @@ print("Hello, world!") #### Ignore block -If Copyright and Licensing Information is declared in a file without describing -the file's or Snippet's actual license or copyright (for example: as part of an -output command or documentation), these occurrences SHOULD be put between two -comments: `REUSE-IgnoreStart` and `REUSE-IgnoreEnd`. The REUSE Tool then ignores -all Copyright and Licensing Information between these comments. This technique -MUST NOT be used to ignore valid Copyright and Licensing Information. +If Licensing Information is declared in a file without describing the file's or +Snippet's actual license or copyright (for example: as part of an output command +or documentation), these occurrences SHOULD be put between two comments: +`REUSE-IgnoreStart` and `REUSE-IgnoreEnd`. The REUSE Tool then ignores all +Licensing Information between these comments. This technique MUST NOT be used to +ignore valid Licensing Information. An example for an ignored block: @@ -204,7 +205,7 @@ echo "SPDX-License-Identifier: MIT" > file.txt ### REUSE.toml -Copyright and Licensing Information MAY be associated with a file through a +Licensing Information MAY be associated with a file through a `REUSE.toml` file. The intended use case of this method is large directories where including a comment header in each file (or in `.license` companion files) is impossible or undesirable. @@ -216,8 +217,8 @@ different directories. The `version` key (REQUIRED) MUST have an integer value representing the schema version of the file. This specification describes version 1 of `REUSE.toml`. -Each `[[annotations]]` table represents an association of Copyright and -Licensing Information to zero or more Covered Files. It has the following keys: +Each `[[annotations]]` table represents an association of Licensing Information +to zero or more Covered Files. It has the following keys: - `path` (REQUIRED), a string or list of strings representing paths. A path MUST use forward slashes as path separators. A path SHOULD resolve to one or more @@ -232,23 +233,23 @@ Licensing Information to zero or more Covered Files. It has the following keys: include a backslash verbatim, use `\\\\`. `\\` followed by any other character is functionally equal to just typing that character. - `precedence` (OPTIONAL), a literal string. It determines the order of - precedence for Copyright and Licensing Information between the `REUSE.toml` file - and Covered Files in the table, and between multiple `REUSE.toml` files if they - both contain Information for the same Covered File. Available values are: + precedence for Licensing Information between the `REUSE.toml` file and Covered + Files in the table, and between multiple `REUSE.toml` files if they both + contain Licensing Information for the same Covered File. Available values are: - `closest`, the default value when `precedence` is not defined. This is an - instruction to associate the Copyright and Licensing Information inside of - the Covered Files, if available. If no such Information is found, then the - Information inside the table of the closest `REUSE.toml` that covers the - File is associated. This algorithm is applied separately for copyright and - for licensing. If a table for the same File in a closer `REUSE.toml` file - has the `override` precedence, then that precedence is applied, and - `closest` is ignored. This is effectively a fallback. - - `aggregate`. This is an instruction to always associate the Copyright and - Licensing Information defined in the table with the table's Covered Files. + instruction to associate the Licensing Information inside of the Covered + Files, if available. If no such Licensing Information is found, then the + Licensing Information inside the table of the closest `REUSE.toml` that + covers the File is associated. This algorithm is applied separately for + copyright and for licensing. If a table for the same File in a closer + `REUSE.toml` file has the `override` precedence, then that precedence is + applied, and `closest` is ignored. This is effectively a fallback. + - `aggregate`. This is an instruction to always associate the Licensing + Information defined in the table with the table's Covered Files. Subsequently, the `closest` logic is also applied. - - `override`. This is an instruction to associate the Copyright and Licensing - Information defined in the table with the table's Covered Files, and to - ignore any other Information that is closer to the Files. The table in the + - `override`. This is an instruction to associate the Licensing Information + defined in the table with the table's Covered Files, and to ignore any other + Licensing Information that is closer to the Files. The table in the `REUSE.toml` that is the closest to the root of the Project is authoritative. - `SPDX-FileCopyrightText` (OPTIONAL), a string or list of strings. Each string @@ -261,9 +262,9 @@ Licensing Information to zero or more Covered Files. It has the following keys: You MAY include other keys and tables to convey additional information. Their semantics are not defined by this specification. -Although the keys to associate Copyright and Licensing Information with the -Covered File are OPTIONAL, the complete Information MUST still be associated -with the File in some fashion. +Although the keys to associate Licensing Information with the Covered File are +OPTIONAL, the complete Licensing Information MUST still be associated with the +File in some fashion. If a Covered File is covered by multiple `[[annotations]]` tables in the same `REUSE.toml` file, then exclusively the last matching table in the file is used @@ -283,10 +284,9 @@ SPDX-License-Identifier = "GPL-3.0-or-later" ### DEP5 (deprecated) -Copyright and Licensing Information MAY be associated with a file through a DEP5 -file, but you SHOULD create a `REUSE.toml` file instead. The DEP5 file is -deprecated, meaning that it is expected to disappear from a future iteration of -this specification. +Licensing Information MAY be associated with a file through a DEP5 file, but you +SHOULD create a `REUSE.toml` file instead. The DEP5 file is deprecated, meaning +that it is expected to disappear from a future iteration of this specification. The DEP5 file MUST be named `dep5` and stored in the `.reuse/` directory in the root of the Project (i.e. `.reuse/dep5`). @@ -312,18 +312,17 @@ License: GPL-3.0-or-later ## Order of precedence -If a Commentable File contains Copyright and Licensing Information but also has -an adjacent `.license` file, then the Copyright and Licensing Information -defined in the `.license` file takes precedence, and the Commentable File's -contents are ignored. For all intents and purposes, this counts as the -`.license` file's Copyright and Licensing Information being inside the -Commentable File. - -Copyright and Licensing Information defined in `.reuse/dep5` is aggregated with -the Copyright and Licensing Information found in the Covered Files. For clarity, -this means that if the SPDX License Expressions in a file's comment header and -in the section for that file in `.reuse/dep5` do not agree with each other, then -both SPDX License Expressions will apply to the file. +If a Commentable File contains Licensing Information but also has an adjacent +`.license` file, then the Licensing Information defined in the `.license` file +takes precedence, and the Commentable File's contents are ignored. For all +intents and purposes, this counts as the `.license` file's Licensing Information +being inside the Commentable File. + +Licensing Information defined in `.reuse/dep5` is aggregated with the Licensing +Information found in the Covered Files. For clarity, this means that if the SPDX +License Expressions in a file's comment header and in the section for that file +in `.reuse/dep5` do not agree with each other, then both SPDX License +Expressions will apply to the file. The order of precedence for `REUSE.toml` files is described in the respective section, and is managed using the `precedence` key. From 738c41b949d509b1eae29e6b16e4dcc61bbfb67f Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 21 May 2024 10:55:40 +0200 Subject: [PATCH 52/55] Add clearer (but tautological) information Signed-off-by: Carmen Bianca BAKKER --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index a94e498..2b50702 100644 --- a/spec.md +++ b/spec.md @@ -35,7 +35,7 @@ These are the definitions for some of the terms used in this specification: holder. Its format is defined in the [Format of Copyright Notices](#format-of-copyright-notices) section. - Covered File --- any file in a Project, except for - - The License Files. + - The License Files stored in the `LICENSES/` directory. - `COPYING` and `LICENSE`, with or without file extensions. - The files belonging to the Project's version control system (example: `.git/`). From 5e6e482a1571959fcd5349550f3c4fde65622ab8 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 21 May 2024 11:09:45 +0200 Subject: [PATCH 53/55] Define TOML in spec Signed-off-by: Carmen Bianca BAKKER --- spec.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/spec.md b/spec.md index 2b50702..e5e4e86 100644 --- a/spec.md +++ b/spec.md @@ -56,7 +56,7 @@ These are the definitions for some of the terms used in this specification: Licensing Information applies. - Uncommentable File --- either a plain text file that cannot contain comments or a file that is not a plain text file. -- SPDX Specification --- SPDX specification, version 2.3; as available on +- SPDX Specification --- SPDX specification, version 2.3; as available at . - SPDX License Identifier --- SPDX short-form identifier, as defined in SPDX Specification. See also for a short introduction and @@ -65,11 +65,13 @@ These are the definitions for some of the terms used in this specification: . - SPDX License List --- a list of commonly found licenses and exceptions; as available on . -- DEP5 --- [Machine-readable `debian/copyright` file, Version - 1.0](https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/). - Where the REUSE Specification and DEP5 state different things, the REUSE +- DEP5 --- Machine-readable `debian/copyright` file, Version 1.0; as available + at . Where + the REUSE Specification and DEP5 state different things, the REUSE Specification takes precedence. Specifically in the case of the `Copyright` and `License` tags. +- TOML --- A configuration file format as available at + . ## License Files @@ -205,10 +207,10 @@ echo "SPDX-License-Identifier: MIT" > file.txt ### REUSE.toml -Licensing Information MAY be associated with a file through a -`REUSE.toml` file. The intended use case of this method is large directories where -including a comment header in each file (or in `.license` companion files) is -impossible or undesirable. +Licensing Information MAY be associated with a file through a `REUSE.toml` file, +which MUST be a valid TOML file. The intended use case of this method is large +directories where including a comment header in each file (or in `.license` +companion files) is impossible or undesirable. A `REUSE.toml` file MAY be located in any directory, and can cover files that are within its directory or deeper. You MAY have multiple `REUSE.toml` files in From 7bddcad2dc7e9a2cb19c63a2d739da397f50f880 Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 21 May 2024 11:26:39 +0200 Subject: [PATCH 54/55] More explicitly state that REUSE.toml only covers its own directory Signed-off-by: Carmen Bianca BAKKER --- spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index e5e4e86..9ebff70 100644 --- a/spec.md +++ b/spec.md @@ -224,7 +224,9 @@ to zero or more Covered Files. It has the following keys: - `path` (REQUIRED), a string or list of strings representing paths. A path MUST use forward slashes as path separators. A path SHOULD resolve to one or more - Covered Files relative to the `REUSE.toml` file's directory. A path MAY use + Covered Files relative to the `REUSE.toml` file's directory. A path that + resolves to a non-existent or non-Covered File is ignored. A path MUST point + to a location in the `REUSE.toml` file's directory or deeper. A path MAY use globbing to match several Covered Files in a single expression. These are the globbing and matching rules: - `*` matches everything except forward slashes (i.e. path separators). From 72aa8a8159a27f5a5e7c304db2d49854317b8aac Mon Sep 17 00:00:00 2001 From: Carmen Bianca BAKKER Date: Tue, 21 May 2024 11:29:40 +0200 Subject: [PATCH 55/55] Explicitly mention `.license` files Signed-off-by: Carmen Bianca BAKKER --- spec.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 9ebff70..d48adc2 100644 --- a/spec.md +++ b/spec.md @@ -242,12 +242,13 @@ to zero or more Covered Files. It has the following keys: contain Licensing Information for the same Covered File. Available values are: - `closest`, the default value when `precedence` is not defined. This is an instruction to associate the Licensing Information inside of the Covered - Files, if available. If no such Licensing Information is found, then the - Licensing Information inside the table of the closest `REUSE.toml` that - covers the File is associated. This algorithm is applied separately for - copyright and for licensing. If a table for the same File in a closer - `REUSE.toml` file has the `override` precedence, then that precedence is - applied, and `closest` is ignored. This is effectively a fallback. + Files (or its adjacent `.license` file), if available. If no such Licensing + Information is found, then the Licensing Information inside the table of the + closest `REUSE.toml` that covers the File is associated. This algorithm is + applied separately for copyright and for licensing. If a table for the same + File in a closer `REUSE.toml` file has the `override` precedence, then that + precedence is applied, and `closest` is ignored. This is effectively a + fallback. - `aggregate`. This is an instruction to always associate the Licensing Information defined in the table with the table's Covered Files. Subsequently, the `closest` logic is also applied.