ros_license_toolkit

Warning For any legal questions, please consult a lawyer. This tool is not a substitute for legal advice.

Motivation

ROS packages must have licenses. This tool checks if the license declarations in the package.xml matches the license(s) of the code. We do this by using scancode-toolkit to scan the code and compare the results to the declaration in the package.xml

Presentation

Functionality

graph TD
    classDef stroke stroke:#333,stroke-width:2px;
    s([scan code for licenses and copyrights])
    class s stroke
    p[compare to\n package.xml\nfor linting]
    class p stroke
    c[create\ncopyright file\nfor release]
    class c stroke
    s --> p
    s --> c

Features

This checks:

• Is package.xml conform to it's schema? - SchemaCheck
• Is any license defined in package.xml? - LicenseTagExistsCheck
• Has at most one license tag without a source-files declaration? - LicenseTagExistsCheck
• Do all licenses tags follow the SPDX standard? - LicenseTagIsInSpdxListCheck
• Are license texts available and correctly referenced for all declared licenses? - LicenseTextExistsCheck
• Does the code contain licenses not declared in any license tags source-file attribute (source-files="src/something/**")? - LicensesInCodeCheck

Usage

Installation

Install the package from source:

pip install .

Basic Usage

You should then have the executable in your $PATH and can run it on any ROS package or a directory containing multiple ROS packages:

ros_license_toolkit my_ros_package

All Options

$ ros_license_toolkit -h
usage: ros_license_toolkit [-h] [-c] [-v] [-q] [-e] [-w] path

Checks ROS packages for correct license declaration.

positional arguments:
  path                  path to ROS2 package or repo containing packages

options:
  -h, --help            show this help message and exit
  -c, --generate_copyright_file
                        generate a copyright file
  -v, --verbose         enable verbose output
  -q, --quiet           disable most output
  -e, --continue_on_error
                        treats all errors as warnings, i.e. will give
                        returncode 0 even on errors
  -w, --warnings_as_error
                        treats all warnings as errors

Additionally, there is an option to ignore single files, folders and types of files. If there exists a .scanignore in the top level directory of a package, everything in it is going to be ignored. The file entries work similar to a .gitignore file, including making comments with #. One Example for a custom .scanignore file:

.git/* # folder
README.txt # file
README.* # file pattern

Per default, ros_license_toolkit ignores the following:

.scanignore
package.xml
setup.py
setup.cfg
CMakeLists.txt
.git/*

Using it as a GitHub action

You can use ros_license_toolkit inside your GitHub workflow in order to check licenses in your repository in each pull request. Use the following job inside your workflow file:

jobs:
  check_licenses:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: boschresearch/ros_license_toolkit@1.2.3

State of Development

WORK IN PROGRESS This is currently working and feature complete to the point it was originally intended. But there are still open points concerning testing and it is also very important to make sure how this behaves with existing ROS packages. In particular, the following things will have to be done:

To Do

• Coverage analysis
• Linter(s) per CI
• Field trials (check existing ROS packages and see what to do with the results). see field-trials/
• Allow license name in tag to be also full name of SPDX key.
• Each LicenseTag should have SPDX id.
• Single license tag without file attribute and single license text should match automatically.
• Turn into github action.
• Evaluate runtime. If scancode-toolkit takes too long on too many cases, we will have to look for an alternative.
• Error of LicenseTagIsInSpdxListCheck must be a warning
• Idea: Create pull requests for package maintainers automatically.

License

ros_license_toolkit is open-sourced under the Apache-2.0 license. See the LICENSE file for details.