No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSES
debian
.gitignore
README.md
build+push.sh
inventory.spdx

README.md

Flight rules for REUSE

What are "flight rules"?

A guide for astronauts (now, programmers making software compliant to the REUSE Initiative) about what to do when things go wrong, or must be executed with no delay.

Flight Rules are the hard-earned body of knowledge recorded in manuals that list, step-by-step, what to do if X occurs, and why. Essentially, they are extremely detailed, scenario-specific standard operating procedures. [...]

NASA has been capturing our missteps, disasters and solutions since the early 1960s, when Mercury-era ground teams first started gathering "lessons learned" into a compendium that now lists thousands of problematic situations, from engine failure to busted hatch handles to computer glitches, and their solutions.

— Chris Hadfield, An Astronaut's Guide to Life.

ps. Idea taken from the GIT flight rules project.


Table of Contents


Licensing

I want to check if my project is REUSE compliant

We use a tool called reuse to see, if the project my-example follows the REUSE recommendations. First, we install it and then we execute it, to see which files are not compliant to the REUSE Initiative.

apt install python3-pygit2
pip3 install --user fsfe-reuse
cd my-example
reuse lint

The result shows a list of files, that do not have licenses associated.

I want to know which license a certain file has

I want to know, which license is associated to the files README.md and example/path/filename.c. We use the reuse tool again:

reuse license README.md example/path/filename.c

The output is a list of files with associated licenses, like this:

README.md
CC-BY-SA-4.0

example/path/filename.c
GPL-3.0

I want to create an inventory for included software

I want to create an inventory or bill of materials of my project, to provide general licensing information and to show which files have which license.

We use the reuse tool:

 reuse compile > inventory.spdx

I want to make my single-license project REUSE compliant

First of all, choose an open source license.

Let's assume you decided to choose the GNU GPL v3.0 for your single-license project.

Download it from https://github.com/spdx/license-list to your project's source code. Then, add the valid SPDX license identifier.

wget https://raw.githubusercontent.com/spdx/license-list/master/GPL-3.0.txt -O LICENSE
sed -i "1iValid-License-Identifier: GPL-3.0" LICENSE

From here, you have three possibilities to continue:

  1. Add a comment header to each file
  2. Use a debian/copyright file to associate a license to various files
  3. Use a combination of both (1) and (2)

In-depth information can be found within the reuse documentation or practices.

I want to make my multi-license project REUSE compliant

First of all, choose an open source license.

Let's assume you decided to choose the GNU GPL v3.0 for your source code and CC-BY-SA-4.0 for your documentation.

Create a LICENSES folder and put your license texts there.

mkdir LICENSES
wget https://raw.githubusercontent.com/spdx/license-list/master/GPL-3.0.txt -O LICENSES/GPL-3.0.txt
wget https://raw.githubusercontent.com/spdx/license-list/master/CC-BY-SA-4.0.txt -O LICENSES/CC-BY-SA-4.0.txt

The SPDX identifier is already encoded within the license file name, hence we do not need to add it to the head of the file itself.

From here, you have three possibilities to continue:

  1. Add a comment header to each file
  2. Use a debian/copyright file to associate a license to various files
  3. Use a combination of both (1) and (2)

In-depth information can be found within the reuse documentation or practices.

I want to add a comment header to each file

Add the following lines as comment to each source code file:

Copyright (C) 2015-2017 Mary Thomas (mary@example.com)
Copyright (C) 2018 IDM Südtirol - Alto Adige (info@idm-suedtirol.com)

SPDX-License-Identifier: GPL-3.0

If you use a version control system, like git, you can also use that history to declare copyright holders, by simply adding a header like this:

This file is part of the Open Data Hub project. It's copyrighted by
the contributors recorded in the version control history of the file,
available from its original location http://git.example.com/odh/filename.c

SPDX-License-Identifier: GPL-3.0

Optionally, you can also add additional license information, like title, short description, and warranty information, as follows:

Open Data Hub - Data Writer for the Open Data Hub

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (see LICENSE). If not, see
<http://www.gnu.org/licenses/>.

NB: Do not forget the SPDX identifier at the end. Add multiple Copyright lines, if you have more than one copyright holder over several years.

I want to add a comment header to each file in my Maven/Java project

We use mycila's maven plugin to add license headers to each file.

Copy header templates for your chosen license to LICENSES/templates/:

mkdir -p LICENSES/templates
cd LICENSES/templates
wget https://raw.githubusercontent.com/mycila/license-maven-plugin/master/license-maven-plugin/src/main/resources/com/mycila/maven/plugin/license/templates/GPL-3.txt -O GPL-3.0-header.txt

Open your pom.xml and add the following section to the <build><plugins> path:

<plugin>
    <groupId>com.mycila</groupId>
    <artifactId>license-maven-plugin</artifactId>
    <version>3.0</version>
    <configuration>
        <header>../LICENSES/templates/GPL-3.0-header.txt</header>
        <properties>
            <owner>IDM Südtirol - Alto Adige</owner>
            <email>info@idm-suedtirol.com</email>
        </properties>
        <excludes>
            <exclude>bin/**</exclude>
            <exclude>**/README</exclude>
            <exclude>src/test/resources/**</exclude>
            <exclude>src/main/resources/**</exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Configure it as you like, with <exclude> patterns and additional <properties>. For a full list of possibilities, see http://code.mycila.com/license-maven-plugin/.

Update license headers:

mvn license:format

I want to define a pattern to associate various files to a license

For this you can use debian/copyright files, also if you are not writing software for the Debian project explicitely.

mkdir debian
vim debian/copyright

An example could be as follows:

Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: idm-suedtirol/bdp-core
Upstream-Contact: Open Data Hub Team <info@opendatahub.bz.it>
Source: https://github.com/idm-suedtirol/bdp-core

Files: *
Copyright: 2000-2017 John Doe <jdoe@example.com>
           2018 IDM Südtirol - Alto Adige (info@idm-suedtirol.com)
License: GPL-3.0-or-later

Files: *.md
Copyright: 2018 IDM Südtirol - Alto Adige (info@idm-suedtirol.com)
License: CC-BY-SA-4.0

This means, that per default files are licensed under GPL-3.0-or-later, except for files ending in .md, which are licensed with CC-BY-SA-4.0. For details on how to write a debian/copyright file, see Debian's packaging manual.

I want to exclude some files from REUSE compliance checking

It is not REUSE compliant, if you do not associate a license to a file inside your source code. Nevertheless, certain files are ignored by reuse, that are either license-specific, or not version-controlled by any VCS.

In detail, the tool reuse ignores all files defined in .gitignore, license-specific folders or files, like LICENSE, LICENCE, *.license, *.spdx, COPYING, and VCS-specific files, as for instance .gitignore, .git, and .svn.

If you want to ignore some files, that you do not need to put into your git repository, do:

vim .gitignore

...and add patterns there.

Otherwise, generate a default license for your whole repository as debian/copyright file. This does not ignore the file, but associates a default license, which is necessary to be REUSE compliant.