REUSE tutorial


!!!THIS IS A ROUGH DRAFT!!!

Our goal

By the end of this tutorial, all your files will clearly have their copyright and licensing marked, and you will be able to verify this using a linter tool.

Your project

For the purpose of this tutorial, we will assume that the directory of your project looks like this:

project/
├── img/
│   ├── cat.png
│   └── dog.png
├── po/
│   ├── de.po
│   ├── en_GB.po
│   ├── eo.po
│   ├── fr.po
│   ├── nl.po
│   └── POTFILES.in
├── src/
│   └── main.c
├── .gitignore
├── Makefile
└── README.md

A license

The first thing you need to do is to choose a license. For this tutorial, we assume that you chose the GNU General Public Licence v3.0 (GPL). More than simply choosing a license, you need to put the licence in your project directory.

In the SPDX License List, you notice that the SPDX Identifier of the license is GPL-3.0-or-later. As such, you create a directory LICENSES, and put the license text from the Free Software Foundation (FSF) in a file called GPL-3.0-or-later.txt.

Header blurb

Now that you have a license, you need to indicate in the relevant files that these files fall under that license. You edit src/main.c as such:

/*
 * SPDX-Copyright: 2019 Jane Doe
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 */

The SPDX-Copyright tag records the publication years and copyright holder of the contents of the file.

The SPDX-License-Identifier tag is followed by a valid SPDX License Expression, typically just the SPDX Identifier of the license.

Each file must always contain these two tags in the header. You are allowed to repeat tags if you have multiple copyright holders or licenses.

You edit Makefile and README.md using this header blurb, though we will need to use the correct comment syntax for each.

Binary files

You also want to license our image files under GPL-3.0-or-later. Unfortunately, images and other binary files do not have comment headers that one can easily edit.

There is a simple trick to circumvent this. Create the files cat.png.license and dog.png.license, each containing the same blurb as above.

A different license

You get a phone call from a photographer who says that the photo they took of their cat was not licensed under the GPL at all. They say it was licensed under Creative Commons Attribution 4.0 International.

You discover that the SPDX Identifier of this license is CC-BY-4.0, and create the file LICENSES/CC-BY-4.0.txt. You edit it to contain the full text of the license.

You then edit cat.png.license to say:

SPDX-Copyright: 2018-2019 Joe Somebody

SPDX-License-Identifier: CC-BY-4.0

Insignificant files

You have a .gitignore file in your project that you do not find particularly copyrightable. You do not want to license this file, but at the beginning of this tutorial, we said that “all your files will clearly have their copyright and licensing marked.” Skipping this file would break that promise.

One way to indicate that you do not exercise any copyright over this file is by marking it as being in the public domain. The CC0 license is a good way to do this. Edit the file to contain:

# SPDX-License-Identifier: CC0-1.0

TODO: No “Copyright” line for these files!

Stubborn files

You have kind translators who translate your project into many different languages. However, your translators do not or cannot edit the headers in their files. You could edit the headers of these files yourself, but there are a lot of them, and you do not feel comfortable manually editing the translation files.

You could use .license files like you did for the images, but for some reason you wish to opt against this.

For these files, you can use a configuration file. In your project root, create the file .reuse/dep5. This file uses Debian’s DEP-5 file format.

You edit the file to look like this:

Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: Project
Upstream-Contact: Jane Doe <jane@example.com>
Source: https://example.com/jane/project

Files: po/*
Copyright: 2018-2019  Translation Company
License: GPL-3.0-or-later

Checking whether you did everything correctly

Now that you have marked all files with their copyright and licensing, it is time to check whether you did not miss anything. To do this, we provide a linter tool for you to use. You can read the full documentation, or read the quick steps below.

$ # Install the dependencies for the tool.
$ sudo apt install python3 python3-pip
$
$ # Install the tool
$ pip3 install --user fsfe-reuse
$
$ # The executable is now in $HOME/.local/bin/.  Make sure that this is in your
$ # $PATH.
$
$ # Go to the directory and run the linter.
$ cd path/to/project/
$ reuse lint
TODO: Figure out human-friendly output maybe.

Result

Your project tree will now look like this:

project/
├── img/
│   ├── cat.png
│   ├── cat.png.license
│   ├── dog.png
│   └── dog.png.license
├── LICENSES/
│   ├── CC0-1.0.txt
│   ├── CC-BY-4.0.txt
│   └── GPL-3.0-or-later.txt
├── po/
│   ├── de.po
│   ├── en_GB.po
│   ├── eo.po
│   ├── fr.po
│   ├── nl.po
│   └── POTFILES.in
├── .reuse/
│   └── dep5
├── src/
│   └── main.c
├── .gitignore
├── Makefile
└── README.md

TODO: Better finishing note.

TODO: Maybe create the above project for real in a read-only repo?