Spec: Allow LICENSES as sub-directory to .reuse

[SebastianWolf-SAP]

Currently, the specification says:

Each License File MUST be placed in the LICENSES/ directory in the root of the Project.

Some of our project maintainers raised concerns about this strict handling of the LICENSES folder as it taints their directory structure too much in their opinion. They want to keep metadata (or anything that is not directly related to their docs, code etc.) in dot-directories such as .reuse.

So the proposal would be that the spec could allow to place the LICENSES directory as a sub-directory underneath .reuse to allow teams to keep their dir structure clean if they want to do so. Of course, that should only be an additional option and not a change to the default.

[silverhook]

I have a very strong opinion against this.

Apart from LICENSES/ being intentionally a very prominent and visible folder, because it does include important information – remember: no license = no rights – it is also intentionally similar to the LICENSE.* file that people and tools are already used to finding. Hiding license texts in a hidden folder is … well, hiding important information.

From the technical PoV, in certain – quite common – cases when copying or moving (e.g. cp repo/* new_repo/), hidden files/folders may not get copied, so this info would be lost. And if the license texts were buried in a hidden folder, it would not be obvious that this info was lost.

In addition, having more than one way to store this (important) information would make the spec much less predictable for both humans and machines.

[SebastianWolf-SAP]

I understand your point, but IMHO it applies as well to the other attribution/copyright/license information that are allowed to be stored in .reuse/dep5 - as alternative to file headers. That has worked as well smoothly so far, so why not allow it for the license texts as well?

[silverhook]

Because certain files simply cannot be edited and that info needs to be stored somewhere. That is why .license files came to be. The DEP5 and later the YAML file are primarily intended for when it would be too bothersome to have many .license files. While a * glob DEP5/YAML file is valid, it is discouraged as it gets rid of most of the benefits of REUSE.

And this is also the reason why the preference is: tags in $file > tags in $file.license > tags and $filename in reuse.dep5/reuse.yaml

I see very little chance that a repository actually cannot have a LICENSES/ folder in place.

[SebastianWolf-SAP]

Well, the dep5 is simply easy and convenient and if I understand the spec correctly, there is no preference between the different options:

There are two ways to associate Copyright and Licensing Information with a file.

And yes, I absolutely agree - a REUSE-compliant project will always have a LICENSES/ directory. I'm only proposing a new place that matches the 2nd alternative that is already possible with copyright and license information.

[silverhook]

There is preference. See quoted spec (emphasis mine, notice also difference between MUST, SHOULD and MAY):

Comment headers

To implement this method, each plain text file that can contain comments MUST contain comments at the top of the file (comment header) that declare that file’s Copyright and Licensing Information.

If a file is not a plain text file or does not permit the inclusion of comments, the comment header that declares the file’s Copyright and Licensing Information SHOULD be in an adjacent file of the same name with the additional extension .license (example: cat.jpg.license if the original file is cat.jpg).

DEP5

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.

If the preference is not clearly enough emphasised, we should make that more clear in the documentation.

[carmenbianca]

Some of our project maintainers raised concerns about this strict handling of the LICENSES folder as it taints their directory structure too much in their opinion.

I'm open to suggestions, but this is not really an actionable use case. If having this directory breaks stuff or causes other obvious issues, then I think we can talk about solutions to those problems, but 'it looks ugly' is a little too subjective. I also agree with @silverhook that caching away licences in a hidden directory probably isn't the best idea.

REUSE is a rather opinionated specification/tool. It takes after Black in some regards. There are some things in Black that I really wish were different and/or configurable, but I can swallow those opinions in the knowledge that Black has largely ended code style discussions and just streamlined+standardised the whole thing, and adding more configurable settings would undermine that goal.

REUSE's goal is to streamline and standardise upstream developers' communication of their copyright and licensing information. Because licensing is complex, and programming is complex, some workarounds for corner cases are needed here and there, but fundamentally, we try to resist the urge to add more configurable options and/or provide even more ways of doing the same thing.

---

As an aside, the sentiment raised in this issue is so prominent that it is the first or second (depending on how you count) question in the FAQ: https://reuse.software/faq/#tradition

I find myself having to say 'no' a lot, and it does pain me that I can't please everyone, but saying 'yes' too often would undermine the project's goals.

[SebastianWolf-SAP]

I was just about to answer to @silverhook's latest comment, then I saw that the issue was already closed. Well, sad news, but let me add some words anyway.

Of course, as project maintainers you need to balance wisely between several aspects and also say no to many of the received requests. I really appreciate that as it's much better than simply ignoring requests or keeping things in a limbo state. However, I kindly ask you to think about this particular one again for a while instead of closing it after not even 24 hours have passed.

Some food for thought:

• REUSE can only make a difference if it's widely adopted. So to make the project successful, you need to listen to some extent to the ones that potentially can make a huge difference. We at SAP are probably one of the biggest adopters of REUSE. We've invested a lot in making our projects compliant and will continue to do so, see e.g. https://github.com/SAP/metadata-creation-tool-for-reuse. Moreover, we also started talking about our (so far positive) experience with REUSE. Closing such a request after not even a day makes me think if I should continue to advertise the adoption of REUSE... That would be bad for the original motivation behind REUSE: Making copyright and license compliance easier and - by that - creating real benefit for the OSS community.
• Referencing https://reuse.software/faq/#tradition is slightly strange. I'm not asking for bringing any old/traditional way back to REUSE - it's quite the opposite.
• You do provide alternatives for projects to decide how they do copyright statements, attribution and license declaration (and even reference the term "undesirable" in the text, but only provide one option for the actual license texts. I'm still convinced that this is inconsistent or to phrase it stronger: double standards...

[carmenbianca]

REUSE can only make a difference if it's widely adopted. So to make the project successful, you need to listen to some extent to the ones that potentially can make a huge difference.

The Rust project recently came to us with a tangible use case in this issue. It took some umming and awwing and looking at the same thing from a few dozen angles, but we were able to work out a reasonable solution after arranging a meeting with them. (I'm not sure the solution made it back to the issue yet; communication is hard.)

I'd be just as happy to do the same here, but I can't work with the issue as given, and the proposed solution has some serious flaws outlined by @silverhook.

Referencing https://reuse.software/faq/#tradition is slightly strange

It's really not. The sentiment is the same—REUSE does something eccentric, and some people dislike it for intangible reasons.

You do provide alternatives for projects to decide how they do copyright statements, attribution and license declaration

Because of real-world restrictions. Image files don't have comment headers, and thus the .license file was born. Some directories may not support loose .license files due to build system or technological restrictions (imagine a directory that can only contain image files, or a directory that contains generated files with unpredictable file names), and thus .reuse/dep5 was born.

I'm really sorry, but 'it taints the directory structure' is not a tangible use case that requires a work-around. It's a matter of taste. I can forgive some of Black's strange formatting decisions and go with the flow. I hope the same can be done for REUSE.

[SebastianWolf-SAP]

REUSE can only make a difference if it's widely adopted. So to make the project successful, you need to listen to some extent to the ones that potentially can make a huge difference.

The Rust project recently came to us with a tangible use case in this issue. It took some umming and awwing and looking at the same thing from a few dozen angles, but we were able to work out a reasonable solution after arranging a meeting with them. (I'm not sure the solution made it back to the issue yet; communication is hard.)

I'd be just as happy to do the same here, but I can't work with the issue as given, and the proposed solution has some serious flaws outlined by @silverhook.

IMHO the flaws are nothing more serious than the ones that you already have in the specification. You already allow the use of dot files for vital metadata and you already provide a second alternative for specifying copyright statements and attribution. Nothing would be worse if you allowed to place LICENSES underneath .reuse. IMHO it would actually better with the option as the license texts would be closer to the actual specification of the copyright and license if people choose to use the 2nd option.

Referencing https://reuse.software/faq/#tradition is slightly strange

It's really not. The sentiment is the same—REUSE does something eccentric, and some people dislike it for intangible reasons.

Well, they are very tangible as it's inconsistent. You allow alternatives for the one thing and don't allow it for the other thing while both aspects are vital for being REUSE compliant.

You do provide alternatives for projects to decide how they do copyright statements, attribution and license declaration

Because of real-world restrictions. Image files don't have comment headers, and thus the .license file was born. Some directories may not support loose .license files due to build system or technological restrictions (imagine a directory that can only contain image files, or a directory that contains generated files with unpredictable file names), and thus .reuse/dep5 was born.

I'm really sorry, but 'it taints the directory structure' is not a tangible use case that requires a work-around. It's a matter of taste. I can forgive some of Black's strange formatting decisions and go with the flow. I hope the same can be done for REUSE.

Build systems and technological restrictions are also made by human beings and therefore also a "matter of taste". In the end such things are no more real-world restrictions than team/company-internal guidelines how they structure their directories. Actually, allowing .reuse/dep5 (because of taste ;)) was a great decision to foster the adoption of REUSE. Allowing LICENSES underneath .reuse would be another plus (also for the acceptance in the teams).

[nicorikken]

I can see the desire for a cleaner folder structure but I don't think hidden files will be of much help as most coders I know have their editor configured to list hidden files too, if only to show the .gitignore, .helmignore and .dockerignore files among others. For the point of view of users/customers I think applicable licenses are relevant, similar to a NOTICE file. Nesting the LICENSES directory into another directory would be nice for coders but less transparent for users. Some editors allow you to hide files and directories: https://www.w3schools.io/editor/vscode-hide-files-folder/

IF we want to allow an alternative (hidden) path besides LICENSES/ I think .reuse is not the right path to put it in, because that would make it specific to REUSE rather than aligning with general existing practices. For example a .LICENSES/ or .licenses/ directory in the root would be better in my opinion.

[silverhook]

OK, if we return to the original proposal and interpret it in the same way as the REUSE headers …

What is the technical (or other strong) reason that you cannot have a LICENSES/ folder in your projects, that would warrant a similar exception as *.license file (which is the basis for the dep5/yaml further exception to it), @SebastianWolf-SAP?

[SebastianWolf-SAP]

As mentioned in the OP: Separate actual content files and folders (directly related to the project) from metadata and administrative content.

But if you allow the comment, the question is a little bit suggestive - of course, we can have a LICENSES/ folder in the root level - we already do that in hundreds of repositories. Several projects actually created a team-internal exception because we in the SAP Open Source Program Office (OSPO) mandated that. On the other side, we at the OSPO want to keep our OSS devs happy - that's why I'm here with this issue.

[silverhook]

And just as from the OP, I still remain unconvinced that moving LICENSES/ to a hidden file is in any way justified by any need, whereby the .license files and consequently the dep5/yaml file are there because of a technical need/limitation.

Sure, it would be conforming to the spec (and esp. tool) if you have an all-encompassing ** glob in the dep5/yaml file, just as it would be if you created a .license file for every single file in the repository. That is unfortunate, but it would be hard to be very specific in the spec exactly when one or the other exception is allowed, let alone enforce that. And the spec already defines which way is preferred.

Ultimately, we all have pushback and specific concerns from our employers’ engineers/clients/colleagues, but not every pushback is reasonable enough to be included into a community-wide spec. Personally, I have a very strong opinion about the format of copyright statements, that I have produced solid legal arguments for, but for the sake of adoption it was decided to be (much) more lenient about that. Your proposal does not seem to benefit either the spec (quite the opposite!) nor its adoption (outside a few projects within SAP, and even there you said you could implement REUSE as is).

[silverhook]

As a thought experiment, if REUSE did not exist, where would you put the LICENSE file in those projects?

[SebastianWolf-SAP]

Alrighty. I'd say the arguments are exchanged. Let's see how things evolve.

As a thought experiment, if REUSE did not exist, where would you put the LICENSE file in those projects?

Of course on root level - by (historic) convention. And yes, that's not a dot file and also would violate the proposal as well, but one thing after another. It's one thing to change a concrete spec and to change a convention that probably older than me...

Actually, we still need to include the LICENSE file as GitHub (or more precisely Licensee) doesn't recognize REUSE (https://github.com/licensee/licensee/issues/490 is still on wontfix). But fortunately, REUSE supports symlinks so folks who are on proper OSs don't need to duplicate the main license file. :)