search

fsfe / reuse-docs

REUSE recommendations, tutorials, FAQ and specification
https://reuse.software
19 stars 20 forks source link

More explicit discussion of the .reuse and LICENSES directories #68

Open uiopaubo opened 4 years ago

uiopaubo commented 4 years ago

The getting started guide is very useful and rather clear, but one is left to assume that the .reuse and LICENSES directories are to be added to the repository being processed. This may seem obvious, but...

  1. Having done all the hard work of licensing everything, it could be easy to forget, with the repository being pushed somewhere without all the licensing details.

  2. There are traditions for separately maintaining meta-information in Free Software communities. For instance, Debian packaging is typically maintained separately from the upstream source distributions. People might assume something similar here.

  3. With the .reuse directory being a hidden directory, it is easy for it to be overlooked. I imagine that one should reference it explicitly in the documentation for the software. Maybe there is some boilerplate mentioning the REUSE initiative that I have not noticed.

Just a few lines at the end of the getting started guide would be very helpful.

mxmehl commented 4 years ago

Thank you for the suggestion, very helpful!

Just to be clear, the .reuse directory is no mandatory. It's just a place for the DEP5 file (if one wants to use that) or addheader templates, and potentially some repo-wide shared config in the future.

The LICENSES directory however is mandatory. I am wondering what exactly is unclear here for readers. Creating this dir is part of the first step. Do you think we should say it after the last step just to be sure?

uiopaubo commented 4 years ago

My concern is that people might forget to add LICENSES (and .reuse) to their repository and then lose these files by failing to share them. I am sure that we have all forgotten to commit files to repositories only to find them untracked later.

The status of the dep5 file is a bit surprising: it contains the project-level licensing metadata, and the manifest can be an extensive catalogue of the file-level licensing, particularly in cases where headers cannot be added to the files. Emphasizing this file would help distributions like Debian significantly.

With regard to boilerplate about these objects, I added the following to projects I am currently auditing:

See the .reuse/dep5 file and the accompanying LICENSES directory in this software's source code distribution for complete copyright and licensing information, including the licensing details of bundled code and content.