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.

Sign up for GitHub

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
Open

New attributes for license tag #347

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b753414
Added attribute source-files in license tag.
ralph-lange Apr 14, 2022
ce3a38b
Added attribute copyright in license tag.
ralph-lange Apr 14, 2022
0efefb3
Added note on the use of the new license tag attributes.
ralph-lange Apr 14, 2022
7fab8c0
Removed newly proposed copyright attribute in license tag.
ralph-lange Apr 28, 2022
2af4e80
Introduced type attribute for license tag.
ralph-lange Apr 21, 2023
1bd1c77
Added example for use of license type attribute.
ralph-lange Apr 21, 2023
a9b3579
Added paragraph on limitation to one filename pattern.
ralph-lange Jun 15, 2023
040c7eb
Added note on spaces in filename patterns.
ralph-lange Jun 15, 2023
007d8b2
Added section on important design decisions.
ralph-lange Mar 13, 2024
49c1b3a
Fixed typo in new design decisions section.
ralph-lange Mar 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 95 additions & 25 deletions rep-0149.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 11-Oct-2017
Post-History: 02-Jan-2018, 31-Aug-2020
Post-History: 02-Jan-2018, 31-Aug-2020, 14-Apr-2022

Outline
=======
Expand Down Expand Up @@ -346,8 +346,8 @@ Example
</description>
<maintainer email="[email protected]">Someone</maintainer>

<license>BSD</license>
<license file="LICENSE">LGPL</license>
<license file="LICENSE" type="spdx">BSD-3-Clause</license>
<license source-files="include/my_package/linear_math/*">Zlib</license>
ralph-lange marked this conversation as resolved.
Show resolved Hide resolved
ralph-lange marked this conversation as resolved.
Show resolved Hide resolved

<url type="website">http://wiki.ros.org/my_package</url>
<url type="repository">http://www.github.com/my_org/my_package</url>
Expand Down Expand Up @@ -465,28 +465,17 @@ Example
<license> (multiple, but at least one)
--------------------------------------

Name of license for this package, e.g. BSD, GPL, LGPL. In order to
assist machine readability, only include the license name in this tag.
For multiple licenses multiple separate tags must be used. A package
will have multiple licenses if different source files have different
licenses. Every license occurring in the source files should have
a corresponding ``<license>`` tag. For any explanatory text about
licensing caveats, please use the ``<description>`` tag.

Most common open-source licenses are described on the
`OSI website <http://www.opensource.org/licenses/alphabetical>`_.

Commonly used license strings:

- Apache-2.0
- BSD
- Boost Software License
- GPLv2
- GPLv3
- LGPLv2.1
- LGPLv3
- MIT
- Mozilla Public License Version 1.1
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
''''''''''
Expand All @@ -505,10 +494,60 @@ Attributes

"You must give any other recipients of the Work or Derivative Works a copy of this License"

``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.

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.

While the Machine-readable debian/copyright file specification V1.0 allows
multiple filename patterns separated by spaces, only one pattern is allowed
here. Use multiple license tags if necessary (but first consider
restructuring the folder structure of the 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.

Finally note that space characters in the source file paths/names - which
should be a very rare case - have to be replaced by a ``?`` in the filename
pattern as described at the end of Section 6.9 of the `Machine-readable
debian/copyright file specification V1.0
<https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_.
Copy link
Contributor

Choose a reason for hiding this comment

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

Why is this required? Since you describe above that multiple space-separated paths are not allowed, I don't understand why we cannot support spaces in paths.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That's how the Machine-readable debian/copyright file specification V1.0 states it. We could do differently, but then we would make the process how the package.xml is translated to the copyright file less transparent. And I consider spaces in source file/folder names an absolute exception.
@ct2034 has built a linter for the new package.xml format, which will of course include a check for space characters.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

If we would simply replace space characters by ? during the generation of the copyright file, this could even change the set of matched files. This must be prevented. Therefore I would force those developers, who want to use space characters in the filenames/paths, to think about it themselves.


``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.


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

</font>

Notes
'''''

The license information given in the license tags has to be consistent
with the information given in the license headers of the source files.
This may be checked by suitable linting tools.

Furthermore, by the license tags in the ``package.xml`` file and the
copyright information obtained from the license headers of the source files
(e.g., using ``licensecheck --copyright``)
a copyright file according to the `Machine-readable debian/copyright file
specification V1.0 <https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_
for binary versions of this package can be created automatically.

<url> (multiple)
----------------

Expand Down Expand Up @@ -1106,6 +1145,37 @@ contained schema file like this:
</font>


Design Decisions
================

This section documents important decisions taken in the design of the package
manifest format and summarizes discussions on the corresponding pull requests
and in the ROS 2 TSC:

* Extensions to ``license`` tag (accepted by ROS 2 TSC on 15 June 2023):
* New optional attribute ``type`` is introduced to specify whether the
license name used in the tag follows the SPDX standard or is freeform.
For the time being, to avoid huge number of errors from legacy packages,
the default value is ``freeform`` and not ``spdx``. However, awareness
for importance of using standardized license names shall be increased
in the community. Furthermore, a corresponding linter warning shall be
implemented.
* For the ``source-files`` attribute two alternatives were discussed:
(1) Single attribute following directly the specification of the
``Files`` field in the `Machine-readable debian/copyright file specification V1.0
<https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`_.
The filename patterns syntax specified in this standard is in parts
rather unusual in the ROS context, in particular the use of space as
separator.
(2) Introduce own syntax for the specification of file sets using
additional (nested) XML tags.
To keep translation of the ``source-files`` attribute to the copyright
file as simple and transparent as possible, the first alternative is
chosen, with the restriction that multiple filename patterns separated
by spaces are not allowed in the attribute value. Instead, multiple
``license`` tags have to be used in this rare case.


References
==========

Expand Down
Loading