Copyright and licensing for REUSE.toml?

[MarkCallow]

After using reuse convert-dep5 I ended up down a rat-hole trying to provide copyright and licensing information for REUSE.toml. I found the whole experience very user unfriendly.

$ reuse convert-dep5
$ reuse lint
# MISSING COPYRIGHT AND LICENSING INFORMATION

The following files have no copyright and licensing information:
* REUSE.toml

I searched for how to include comments in a .toml file. Then I read the REUSE.toml section of the REUSE specification v3.2 which says nothing about this info being required or how to provide it. So I tried the following. None of them worked.

version = 1
SPDX-PackageName = "KTX-Software"
SPDX-PackageDownloadLocation = "https://github.com/KhronosGroup/KTX-Software"
SPDX-FileCopyrightText = "2024 The Khronos Group Inc."
SPDX-License-Identifier = "Apache-2.0"

version = 1
SPDX-FileCopyrightText = "2024 The Khronos Group Inc."
SPDX-License-Identifier = "Apache-2.0"
SPDX-PackageName = "KTX-Software"
SPDX-PackageDownloadLocation = "https://github.com/KhronosGroup/KTX-Software"

version = 1
SPDX-PackageName = "KTX-Software"
SPDX-PackageDownloadLocation = "https://github.com/KhronosGroup/KTX-Software"
# SPDX-FileCopyrightText = "2024 The Khronos Group Inc."
# SPDX-License-Identifier = "Apache-2.0"

Then I tried

version = 1
SPDX-PackageName = "KTX-Software"
SPDX-PackageDownloadLocation = "https://github.com/KhronosGroup/KTX-Software"

[[annotations]]
SPDX-FileCopyrightText = "2024 The Khronos Group Inc."
SPDX-License-Identifier = "Apache-2.0"

which produced

usage: reuse [-h] [--debug] [--suppress-deprecation] [--include-submodules]
             [--include-meson-subprojects] [--no-multiprocessing]
             [--root PATH] [--version]
             {annotate,download,lint,spdx,supported-licenses,supported-licences,convert-dep5}
             ...
reuse: error: '.' could not be parsed. We received the following error message: 'path' must not be empty.

Note the conspicuous absence of a line number where the parsing error was. In this case since I had just added the annotation, I knew were the error had to be. Nevertheless, in my view, failing to provide line numbers or context in such errors is a sackable offence.

Finally I tried

version = 1
SPDX-PackageName = "KTX-Software"
SPDX-PackageDownloadLocation = "https://github.com/KhronosGroup/KTX-Software"

[[annotations]]
path = "REUSE.toml"
SPDX-FileCopyrightText = "2024 The Khronos Group Inc."
SPDX-License-Identifier = "Apache-2.0"

The first way I tried seemed the most logical to me. The way that I eventually found worked seems circular to me.

Why require copyright and licensing info for REUSE.toml? It wasn't required for dep5. If it must be provided, convert-dep5 should print a message about it with information about how to add it. Even better it could prompt for the copyright string and license name and add it to the file itself.

[carmenbianca]

Hi @MarkCallow ! We discussed this same problem internally last Friday. We're in agreement that we should change this.

Regarding how to solve this for now:

# SPDX-FileCopyrightText: 2024 Jane Doe
# 
# SPDX-License-Identifier: CC0-1.0

version = 1

[[annotations]]
key = "value"

[MarkCallow]

Hi @MarkCallow ! We discussed this same problem internally last Friday. We're in agreement that we should change this.

Change it how?

Regarding how to solve this for now:

# SPDX-FileCopyrightText: 2024 Jane Doe
# 
# SPDX-License-Identifier: CC0-1.0

version = 1

[[annotations]]
key = "value"

Thanks. That worked.

[carmenbianca]

Change it how?

REUSE.toml probably should not require such a licensing header.

[Huy-Ngo]

I noticed that REUSE.toml is not lised in the ignored files in the spec

[paddy-hack]

REUSE.toml probably should not require such a licensing header.

Considering that .reuse/dep5 does not require one, that makes sense.\ Actually, .reuse/dep5 is not checked for a header to begin with because the whole .reuse direcotry is ignored.

On the other hand, it might be nice to suggest adding a licensing header, using the TOML comment syntax shown above.

[trinitronx]

Just noticed this too with top-level REUSE.toml while starting to use this tool for the first time. Maybe this experience helps as a UX "user journey" from a newcomer's perspective?

First, I created a few files and configured licensing in REUSE.toml at top-level of the repo. I ran reuse lint to try and verify that they were covered by the REUSE.toml:

$ reuse lint
# MISSING COPYRIGHT AND LICENSING INFORMATION

The following files have no licensing information:
* REUSE.toml

[...SNIP...]

So, reuse lint wants to also have license specified for its' own config file... OK, let's see what can be done? Maybe it falls under the "Ignored Files" category?

I first read the following in the "Covered and Ignored Files" section of the REUSE Specification

Covered Files are any file which must contain Licensing Information. This is equal to all files in a project, with the exception of:

[...SNIP...]

• The files in the .reuse/ directory in the root of the Project. This directory MUST contain only files relevant for the operation of the REUSE Tool.

So, thinking that since the old .reuse/dep5 file was located in the .reuse/ directory, I placed REUSE.toml in there too. Then the warning for REUSE.toml went away, but new warnings were returned for files that had previously been configured in REUSE.toml:

# MISSING COPYRIGHT AND LICENSING INFORMATION

The following files have no copyright and licensing information:
* NEW
* README.md

[...SNIP...]

So, now the tool appears to be ignoring the configuration file where I had configured licenses for these other files. It must be only looking for it at the top-level where it was before? OK... Let's specify instead the license for that file itself:

$ reuse annotate --copyright-prefix spdx-symbol --year 2023-2024  --copyright 'Free Software Foundation, Inc. <https://fsf.org>' --style=python --license CC0-1.0  --copyright 'James Cuzella <james.cuzella@member.fsf.org>' REUSE.toml

Re-running the reuse lint shows that now it's applying configuration:

# MISSING LICENSES

'CC0-1.0' found in:
* REUSE.toml

[...SNIP...]

Downloading the CC0-1.0 into ./LICENSES/, re-checking, and now it shows everything is good 👍 :

$ reuse download --all
Successfully downloaded LICENSES/CC0-1.0.txt.

$ reuse lint

# SUMMARY

* Bad licenses: 0
* Deprecated licenses: 0
* Licenses without file extension: 0
* Missing licenses: 0
* Unused licenses: 0
* Used licenses: CC0-1.0, BSD-2-Clause, AGPL-3.0-or-later
* Read errors: 0
* Files with copyright information: 6 / 6
* Files with license information: 6 / 6

Congratulations! Your project is compliant with version 3.2 of the REUSE Specification :-)

Things that could have been documented to better assist this user journey:

1. Document that the main REUSE.toml should be at the top-level, and not in .reuse/ directory.

2. Document whether REUSE.toml itself is supposed to have a license (or not... if that's what is decided)

   • If REUSE.toml should not have a license, then ignore it by default
   • This avoids the whole user journey described above, and is probably simpler
   • If it's decided that REUSE.toml should have a license..
   • Perhaps suggest the CC0-1.0 or some other license?
   • Maybe document the suggested license to apply via a reuse annotate ... command as I did above,

   • AND/OR via a path = "REUSE.toml" configuration snippet?

     [[annotations]] path = "REUSE.toml" SPDX-FileCopyrightText = [ "© 2023-2024 Free Software Foundation, Inc. https://fsf.org", "© YYYY Jane Doe jdoe@example.org" ] SPDX-License-Identifier = "CC0-1.0"

3. Document what is the purpose of .reuse/ directory with modern versions of the reuse tool.

   • Is this directory still expected to be used when not in .reuse/dep5 compatibility mode?
   • I see that #1054 was closed as WONTFIX... Does this mean that .reuse directory is not to be used anymore, since it is a hidden directory? 🤷

I think most of this can be addressed by clarifying the documentation. If the REUSE.toml needs to be ignored by default, it would be a simple code change to handle it similarly to .reuse/ directory.

[Huy-Ngo]

Does this mean that .reuse directory is not to be used anymore, since it is a hidden directory?

The dep5 file is deprecated and may be removed in a future version, so yea.

[carmenbianca]

Hi @trinitronx ! Thanks for your detailed overview of your attempt at solving the issue.

I will respond to a few things that may be useful to you.

1. Document that the main REUSE.toml should be at the top-level, and not in .reuse/ directory.

This is documented in the spec, under the 'REUSE.toml' header: '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 FAQ entry for REUSE.toml also answers this: 'You can license files globally using the REUSE.toml file, typically placed in the root of your project, but it can be placed anywhere relative to the files.'

I hope that these places suffice for documentation. I will also improve the wording in the man page, because the wording is a little scarce (and maybe even misleading) there.

2. Document whether REUSE.toml itself is supposed to have a license (or not... if that's what is decided)

Per https://github.com/fsfe/reuse-website/pull/83 and #1042, REUSE.toml need not have licensing information in the future.

3. Document what is the purpose of .reuse/ directory with modern versions of the reuse tool.

With the deprecation of .reuse/dep5, the .reuse/ directory is only used by annotation templates. In the future, I may use it for #68 (related to #534), but it's a little lower on the priority scale at the moment.

The specification says this about the .reuse directory: 'The files in the .reuse/ directory in the root of the Project. This directory MUST contain only files relevant for the operation of the REUSE Tool.'

---

I hope that helps! If you have specific pointers for improved documentation that I have overlooked, please let me know. I do my best, but documentation is hard.