REUSE - noi-techpark/odh-docs GitHub Wiki

REUSE is a project by the Free Software Foundation Europe aimed at making licensing for open source software easier.

A REUSE compliant project is guaranteed to have machine readable as well as human readable licensing and copyright information for individual files and is certain to always refer to up to date licenses listed in the SPDX Specification.

REUSE also provides tooling to continuously check for missing information and to automate parts of the development workflow concerning the management of copyright and licensing information.

Table of Contents

• Guidelines
• Tools
  • Helper Tool
  • Github Action
  • Pre Commit Hook
• Badges
  • Official Badge
  • CI Workflow Badge

Guidelines

For a project to be REUSE compliant, every file must be associated with its corrisponding copyright and licensing information. Since REUSE provides multiple methods to achieve this we have settled on some guidelines for our projects:

1. Files which have syntax for comments such as source code files but also files like a README.md should contain a header holding at least the two mandatory SPDX tags which are SPDX-FileCopyrightText and SPDX-License-Identifier. An example header might look like this:

/*
 * SPDX-FileCopyrightText: NOI Techpark <[email protected]>
 *
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

2. Files which cannot contain headers such as binaries or assets should be listed in the .reuse/dep5 file of the project.
3. Files which are associated with copyright and licensing information through a header should not be listed in the dep5 file.
4. Directories which contain auto-generated content should be listed in the dep5 file.

Files and directories which are already listed in the .gitignore file of the project will automatically be ignored.

Files with unknown licenses

If it's impossible to determine the original license of a file, you can annotate it with a custom LicenseRef: e.g. // SPDX-License-Identifier: LicenseRef-FIXME-Unknown-Author
then create a file LICENSES/LicenseRef-FIXME-Unknown-Author.txt in which you document the isses with licensing

This way you can remain reuse compliant

Tools

Helper Tool

The REUSE helper tool can be used to automate some of the tasks required to achieve REUSE compliance:

• reuse init generates the "boilerplate" files and downloads the necessary license files to start making a project REUSE compliant.
• reuse annotate auto-generates headers for files with known file extensions, this makes it easy to generate headers for a large number of files or a deeply nested directory structure with the -r recursive flag.
• reuse download makes it easy to download up to date and correct license texts.
• reuse lint enables you to test your project locally for REUSE compliance.

The most common commands for annotating files, adapted for NOI Techpark repositories are the following:

• For source code files:

reuse annotate --copyright="NOI Techpark <[email protected]>" --license="AGPL-3.0-or-later" --exclude-year <file-patterns>

• For other files:

reuse annotate --copyright="NOI Techpark <[email protected]>" --license="CC0-1.0" --exclude-year <file-patterns>

Github Action

The REUSE Compliance Check is a Github Action which automatically tests a Github repository for REUSE compliance on every push when integrated in its CI. Most of our projects include this test in their CI, so no changes to a project will be deployed if they are not REUSE compliant.

Pre Commit Hook

When making a lot of changes on a project it can be annoying if the CI fails regularly because of the REUSE Compliance Check, therefore all of our projects which have a CI configured also contain a .pre-commit-config.yaml file at the project root. This file can be used in combination with pre-commit, a tool which makes installing git hooks easy, to install a pre-commit hook which checks for REUSE compliance on every commit.

Install pre-commit:

pip install pre-commit

Install the git hook (in the project root):

pre-commit install

If you want to uninstall the git hook:

pre-commit uninstall

Badges

Official Badge

Public repositories can be registered with the REUSE API, they are then checked regularly for compliance and a badge is automatically generated. This badge can then be included in the projects README.md.

CI Workflow Badge

Since REUSE asks not to register to many projects at once, not all projects contain the official REUSE badge. To still show that a project is currently REUSE compliant, all repositories with a CI contain a separate workflow checking only for REUSE compliance. The separate badge for this workflow is then included in the projects README.md.