Closed MarkCallow closed 1 month ago
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"
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.
Change it how?
REUSE.toml probably should not require such a licensing header.
I noticed that REUSE.toml is not lised in the ignored files in the spec
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.
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:
Document that the main REUSE.toml
should be at the top-level, and not in .reuse/
directory.
Document whether REUSE.toml
itself is supposed to have a license (or not... if that's what is decided)
REUSE.toml
should not have a license, then ignore it by defaultREUSE.toml
should have a license..CC0-1.0
or some other license?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"
Document what is the purpose of .reuse/
directory with modern versions of the reuse
tool.
.reuse/dep5
compatibility mode?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.
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.
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.
- 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.
- 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.
- 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.
After using
reuse convert-dep5
I ended up down a rat-hole trying to provide copyright and licensing information forREUSE.toml
. I found the whole experience very user unfriendly.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.
Then I tried
which produced
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
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 fordep5
. 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.