Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New attributes for license tag #347

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Prev Previous commit
Next Next commit
Introduced type attribute for license tag.
Signed-off-by: Ralph Lange <[email protected]>
ralph-lange committed Apr 21, 2023
commit 2af4e8075c6c166559822a236d371153a322543f
48 changes: 30 additions & 18 deletions rep-0149.rst
Original file line number Diff line number Diff line change
@@ -465,18 +465,21 @@ Example
<license> (multiple, but at least one)
--------------------------------------

Name of license for this package or selected files of this package,
e.g. BSD-3-Clause, GPL-3.0-or-later, Apache-2.0. In order to assist
machine readability, only include the `SPDX license identifier
<https://spdx.org/licenses/>`_ in this tag. In the rare case that
a package (or selected source files of the package) are licensed under
multiple alternative licenses, the identifiers can be combined by
``or`` as described in Section 7.2 of the `Machine-readable
Name of license for this package or selected files of this package, e.g.,
``BSD-3-Clause``, ``GPL-3.0-or-later``, ``Apache-2.0``. In order to assist
machine readability, it is strongly recommended to use `SPDX license
identifiers <https://spdx.org/licenses/>`_ in this tag and to document
the use of SPDX by the ``type`` attribute.

In the rare case that a package (or selected source files of the package)
are licensed under multiple alternative licenses, the identifiers can be
combined by ``or`` as described in Section 7.2 of the `Machine-readable
debian/copyright file specification V1.0
<https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_.

Attributes
''''''''''

.. raw:: html

<font color="blue">
@@ -493,19 +496,28 @@ Attributes

``source-files="FILENAME-PATTERN"`` *(optional)*

A filename pattern using the simplified shell glob syntax specified in Section 6.9 of the `Machine-readable
debian/copyright file specification V1.0 <https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_
and relative to the ``package.xml`` file.
A filename pattern using the simplified shell glob syntax specified in
Section 6.9 of the `Machine-readable debian/copyright file specification V1.0
<https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_ and
relative to the ``package.xml`` file.

The filename pattern specifies the source files this license information
refers to. The value ``source-files="*"`` refers to all source files of the
package, including source files that are downloaded automatically during the
build process - for example in the case of so-called *vendor packages*. If
the attribute is not specified, the tag again refers to all source files of
the package, including downloaded source files.

If the filename patterns of multiple license tags match a particular file,
the last tag applies to it - following the logic described in Section 6.9
of the `Machine-readable debian/copyright file specification V1.0
<https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_.
Consequently, more general tags should be given first.

The filename pattern specifies the source files this license information refers to. The value
``source-files="*"`` refers to all source files of the package, including source files that are downloaded automatically
during the build process - for example in the case of so-called *vendor packages*. If the attribute is not specified,
the tag again refers to all source files of the package, including downloaded source files.
``type="LICENSE-IDENTIFIER-TYPE"`` *(optional)*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be better to eliminate this type attribute. I haven't seen it in any other package managers. We can still state that the license SHOULD be an SPDX identifier (and linter can throw a warning).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that this is important to have as a way to suppress linter errors. In particular, I think that we should change it to be spdx is the default type. As that should be our recommendation. But if you have a non-spdx license you can set it to be "freeform" explicitly and then the linter will be suppressed and not complain about the string not matching spdx.

This will encourage spdx by it being the shortest path to usage. And if they aren't using an spdx license people can be given a linting warning. And the fix for the linter is to either fix their license declaration to be spdx compatible, or declare that it's freeform with the non-default type attribute.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If spdx is the default that works 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am also in favor of making spdx the standard. @clalancette understandably argued that this would lead to very many error messages for older packages.

Idea: We make freeform the default (as currently stated in this PR and approved by the TSC yesterday) but make a prominent info message in the linter tooling if the type-attribute is not specified explicitly and the license identifier is not from the SPDX list. Furthermore, we raise awareness for the license documentation topic by a Discourse post and a ROSCon talk. Then, in about a year, we can consider changing the default of the type attribute to SPDX (by a new PR to this REP) to force the maintainers of the remaining packages to resolve/clarify the license documentation. What do you think, @amacneil, @clalancette ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for doing a followup/tick tock process to make it the default with strong linting/warning. But lets close this out first.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the way I would do this is the following:

  1. Make freeform the default for now.
  2. Raise awareness with the Discourse post and ROSCon talk.
  3. Update the core packages (everything in https://github.com/ros2/ros2/blob/rolling/ros2.repos) to use SPDX.
  4. Add in a linter warning in ament_copyright for packages that don't specify the type and the identifier is not in SPDX.
  5. Later on, consider changing the default to SPDX.


If the filename patterns of multiple license tags match a particular file, the last tag applies to it - following
the logic described in Section 6.9 of the `Machine-readable
debian/copyright file specification V1.0 <https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_.
Consequently, more general tags should be given first.
The type of license identifier being used in the tag. The type should be one
of the following identifiers: ``freeform`` (default) or ``SPDX``.

.. raw:: html