From b753414bcf694558012a9861cb9bb3bc21e88c87 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 14 Apr 2022 21:26:03 +0200 Subject: [PATCH 01/10] Added attribute source-files in license tag. Signed-off-by: Ralph Lange --- rep-0149.rst | 54 +++++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/rep-0149.rst b/rep-0149.rst index 4cbf405d..a65acff9 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -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, 04-Apr-2022 Outline ======= @@ -346,8 +346,8 @@ Example Someone - BSD - LGPL + BSD-3-Clause + Zlib http://wiki.ros.org/my_package http://www.github.com/my_org/my_package @@ -465,32 +465,18 @@ Example (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 ```` tag. For any explanatory text about -licensing caveats, please use the ```` tag. - -Most common open-source licenses are described on the -`OSI website `_. - -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, only include the `SPDX license identifier +`_ 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 +debian/copyright file specification V1.0 +`_. Attributes '''''''''' - .. raw:: html @@ -505,6 +491,22 @@ 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 `_ + 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 `_. + Consequently, more general tags should be given first. + .. raw:: html From ce3a38bb09e9ffe0c6b6864072f314dc9a7ddd9a Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 14 Apr 2022 21:46:17 +0200 Subject: [PATCH 02/10] Added attribute copyright in license tag. Signed-off-by: Ralph Lange --- rep-0149.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/rep-0149.rst b/rep-0149.rst index a65acff9..3777d999 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -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, 04-Apr-2022 +Post-History: 02-Jan-2018, 31-Aug-2020, 14-Apr-2022 Outline ======= @@ -507,6 +507,14 @@ Attributes debian/copyright file specification V1.0 `_. Consequently, more general tags should be given first. + ``copyright="COPYRIGHT HOLDER INFORMATION"`` *(optional)* + + Information about copyright holders of the source files this tag refers to. The attribute value is considered in addition to the + copyright information given in the license headers of those source files. In case of normal source files with proper license header + this attribute is not required. It is particularly intended for vendor packages, which download the source code during + the build process from another repository, i.e., where the actual source files are not stored in the current repository + and thus not available to tools that analyze the source code of the current package only. + .. raw:: html From 0efefb33466d0b6e86729ec73be552dddfb9d656 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 14 Apr 2022 21:52:01 +0200 Subject: [PATCH 03/10] Added note on the use of the new license tag attributes. Signed-off-by: Ralph Lange --- rep-0149.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/rep-0149.rst b/rep-0149.rst index 3777d999..36223520 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -519,6 +519,20 @@ Attributes +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 `_ +for binary versions of this package can be created automatically. + (multiple) ---------------- From 7fab8c01f6a2ea6ad2a6bc5ba3349eb52aca92e3 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 28 Apr 2022 17:27:45 +0200 Subject: [PATCH 04/10] Removed newly proposed copyright attribute in license tag. Signed-off-by: Ralph Lange --- rep-0149.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/rep-0149.rst b/rep-0149.rst index 36223520..09324f01 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -507,14 +507,6 @@ Attributes debian/copyright file specification V1.0 `_. Consequently, more general tags should be given first. - ``copyright="COPYRIGHT HOLDER INFORMATION"`` *(optional)* - - Information about copyright holders of the source files this tag refers to. The attribute value is considered in addition to the - copyright information given in the license headers of those source files. In case of normal source files with proper license header - this attribute is not required. It is particularly intended for vendor packages, which download the source code during - the build process from another repository, i.e., where the actual source files are not stored in the current repository - and thus not available to tools that analyze the source code of the current package only. - .. raw:: html From 2af4e8075c6c166559822a236d371153a322543f Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Fri, 21 Apr 2023 11:21:37 +0200 Subject: [PATCH 05/10] Introduced type attribute for license tag. Signed-off-by: Ralph Lange --- rep-0149.rst | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/rep-0149.rst b/rep-0149.rst index 09324f01..83894390 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -465,18 +465,21 @@ Example (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 -`_ 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 `_ 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 `_. Attributes '''''''''' + .. raw:: html @@ -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 `_ - 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 + `_ 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 + `_. + 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)* - 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 `_. - 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 From 1bd1c77d30458a05df4443e6ed76338cdd0b10c9 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Fri, 21 Apr 2023 11:25:31 +0200 Subject: [PATCH 06/10] Added example for use of license type attribute. Signed-off-by: Ralph Lange --- rep-0149.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rep-0149.rst b/rep-0149.rst index 83894390..ebde99f2 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -346,7 +346,7 @@ Example Someone - BSD-3-Clause + BSD-3-Clause Zlib http://wiki.ros.org/my_package @@ -517,7 +517,7 @@ Attributes ``type="LICENSE-IDENTIFIER-TYPE"`` *(optional)* The type of license identifier being used in the tag. The type should be one - of the following identifiers: ``freeform`` (default) or ``SPDX``. + of the following identifiers: ``freeform`` (default) or ``spdx``. .. raw:: html From a9b35795444f4e8225259f9c924f3a691cf68a41 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 15 Jun 2023 12:22:19 +0200 Subject: [PATCH 07/10] Added paragraph on limitation to one filename pattern. Signed-off-by: Ralph Lange --- rep-0149.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/rep-0149.rst b/rep-0149.rst index ebde99f2..b7a144ae 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -508,6 +508,11 @@ Attributes 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 From 040c7ebedd5255ac1255be20c11798dd86cd2cf1 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 15 Jun 2023 12:30:45 +0200 Subject: [PATCH 08/10] Added note on spaces in filename patterns. Signed-off-by: Ralph Lange --- rep-0149.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/rep-0149.rst b/rep-0149.rst index b7a144ae..9b4047cb 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -519,6 +519,12 @@ Attributes `_. 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 + `_. + ``type="LICENSE-IDENTIFIER-TYPE"`` *(optional)* The type of license identifier being used in the tag. The type should be one From 007d8b2de93bd076e9e41eef6ad75a36a8ed3015 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Wed, 13 Mar 2024 11:56:09 +0100 Subject: [PATCH 09/10] Added section on important design decisions. Signed-off-by: Ralph Lange --- rep-0149.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/rep-0149.rst b/rep-0149.rst index 9b4047cb..a5aa66a1 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -1145,6 +1145,37 @@ contained schema file like this: +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 + `_. + 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 spacse are not allowed in the attribute value. Instead, multiple + ``license`` tags have to be used in this rare case. + + References ========== From 49c1b3a45cebc9c01004d8a59e73df2ae1431025 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Thu, 14 Mar 2024 15:08:46 +0100 Subject: [PATCH 10/10] Fixed typo in new design decisions section. Signed-off-by: Ralph Lange --- rep-0149.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rep-0149.rst b/rep-0149.rst index a5aa66a1..041a9d56 100644 --- a/rep-0149.rst +++ b/rep-0149.rst @@ -1172,7 +1172,7 @@ and in the ROS 2 TSC: 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 spacse are not allowed in the attribute value. Instead, multiple + by spaces are not allowed in the attribute value. Instead, multiple ``license`` tags have to be used in this rare case.