Skip to contentSkip to conversation

migration-guide: Add guide for converting licenses

PATCH Superseded Joshua Watt 3 participants 6 messages Jul 21 – Jul 31

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 migration-guide: Add guide for converting licenses

The LICENSE variable is now required to be SPDX license expressions, so provide a migration guide to describe the changes required to integrate this change

---
 .../migration-guides/migration-6.1.rst        | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
documentation/migration-guides/migration-6.1.rst +58 -0
index 8786cd699..48777e16c 100644
@@ -75,6 +75,61 @@ And::
 
    oe.utils.any_distro_features("x y", ...) -> bb.utils.contains_any("DISTRO_FEATURES", "x y", ...)
 
+``LICENSE`` is now a SPDX License Expression
+--------------------------------------------
+
+The ``LICENSE`` variable is now an `SPDX License Expression`_ instead of the
+custom license expressions that have been used historically.
+
+The changes required for the new expressions are as follows:
+1. The ``&`` operator is replaced with ``AND``
+
+2. The ``|`` operator is replaced with ``OR``
+
+3. Any license value which is not a valid `SPDX License Expression`_ is an
+   error.
+
+4. Custom (non `SPDX License Identifier`_) licenses are still allowed, as long
+   as they are prefixed with ``LicenseRef-``. The behavior of looking for the
+   license text in ``LICENSE_PATH`` (with or without the ``LicenseRef-``
+   prefix) or ``NO_GENERIC_LICENSE`` is unchanged, and may still be used.
+
+5. ``CLOSED`` as a license is deprecated and will issue a warning. This license
+   is effectively "no license" (usually meaning e.g. "All rights reserved"),
+   but a more precise definition is to provide some sort of actual license text
+   using a custom license. This provides a more consistent definition of the
+   license text, since the meaning of "no license" may vary by jurisdiction.
+   Keep in mind that you can still have a common license file in
+   ``LICENSE_PATH`` and refer to it with a ``LicenseRef-`` license. Note that
+   when you this, you will also need to provide a ``LIC_FILE_CHKSUM`` value to
+   point to your license file.
+
+6. The ``WITH`` operator should now be used to describe an exception to a
+   license, instead of a bespoke license identifier. For example, the old
+   bespoke license ``Apache-2.0-with-LLVM-exception`` would become
+   ``Apache-2.0 WITH LLVM-exception``.
+
+7. Because of the change to use ``WITH`` instead of bespoke licenses, there is
+   a change in how ``INCOMPATIBLE_LICENSE`` works. Anything listed in this
+   variable will match a single licenses (unchanged), but it will also match the
+   left-hand (license) side of a ``WITH`` expression. To allow a license with a
+   specific SPDX license exception, the SPDX license exception must be listed in
+   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
+
+   Practically speaking, the place where this comes up the most is when
+   attempting to exclude GPLv3 code using ``INCOMPATIBLE_LICENSE``. Previously,
+   this would have allowed any ``GPLv3-with-exception`` license, since they
+   were bespoke licenses that did not match the ``GPL-3.0* LGPL-3.0*``
+   expansion. Now, however, the licenses will match because they are e.g.
+   ``GPL-3.0-or-later WITH exception``. As such, any exceptions to the GPLv3
+   that should be allowed must be listed in
+   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
+
+Currently, the older syntax for license expressions is still parsed and
+automatically converted to an SPDX License Expression, but a warning is issued
+when this occurs. This support will eventually be removed and the only valid
+values for these variables will be SPDX License Expressions.
+
 Removed recipes
 ---------------
 
@@ -93,3 +148,6 @@ Removed classes
 
 Miscellaneous changes
 ---------------------
+
+.. _SPDX License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/
+.. _SPDX License Identifier: https://spdx.org/licenses/
Signature · 1 line
2.54.0
#1 lore raw

Hi Joshua,

just a few typos I came across.

Quoted 14 lines · Joshua Watt via lists.yoctoproject.org

The LICENSE variable is now required to be SPDX license expressions, so provide a migration guide to describe the changes required to integrate this change

---
 .../migration-guides/migration-6.1.rst        | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
documentation/migration-guides/migration-6.1.rst +0 -0
index 8786cd699..48777e16c 100644

documentation/migration-guides/migration-6.1.rst And:: · line 84

Quoted 10 lines
documentation/migration-guides/migration-6.1.rst +7 -0
@@ -75,6 +75,61 @@ And::
 
    oe.utils.any_distro_features("x y", ...) -> bb.utils.contains_any("DISTRO_FEATURES", "x y", ...)
 
+``LICENSE`` is now a SPDX License Expression
+--------------------------------------------
+
+The ``LICENSE`` variable is now an `SPDX License Expression`_ instead of the
+custom license expressions that have been used historically.
+
+The changes required for the new expressions are as follows:

I'm unsure, should there be an empty line here before the enumerated list in RST?

Quoted 10 lines
documentation/migration-guides/migration-6.1.rst +10 -0
+1. The ``&`` operator is replaced with ``AND``
+
+2. The ``|`` operator is replaced with ``OR``
+
+3. Any license value which is not a valid `SPDX License Expression`_ is an
+   error.
+
+4. Custom (non `SPDX License Identifier`_) licenses are still allowed, as long
+   as they are prefixed with ``LicenseRef-``. The behavior of looking for the
+   license text in ``LICENSE_PATH`` (with or without the ``LicenseRef-``

documentation/migration-guides/migration-6.1.rst And:: · line 104

Quoted 10 lines
documentation/migration-guides/migration-6.1.rst +10 -0
+   prefix) or ``NO_GENERIC_LICENSE`` is unchanged, and may still be used.
+
+5. ``CLOSED`` as a license is deprecated and will issue a warning. This license
+   is effectively "no license" (usually meaning e.g. "All rights reserved"),
+   but a more precise definition is to provide some sort of actual license text
+   using a custom license. This provides a more consistent definition of the
+   license text, since the meaning of "no license" may vary by jurisdiction.
+   Keep in mind that you can still have a common license file in
+   ``LICENSE_PATH`` and refer to it with a ``LicenseRef-`` license. Note that
+   when you this, you will also need to provide a ``LIC_FILE_CHKSUM`` value to

s/when you this/when you do this/

documentation/migration-guides/migration-6.1.rst And:: · line 114

Quoted 10 lines
documentation/migration-guides/migration-6.1.rst +10 -0
+   point to your license file.
+
+6. The ``WITH`` operator should now be used to describe an exception to a
+   license, instead of a bespoke license identifier. For example, the old
+   bespoke license ``Apache-2.0-with-LLVM-exception`` would become
+   ``Apache-2.0 WITH LLVM-exception``.
+
+7. Because of the change to use ``WITH`` instead of bespoke licenses, there is
+   a change in how ``INCOMPATIBLE_LICENSE`` works. Anything listed in this
+   variable will match a single licenses (unchanged), but it will also match the

s/will match a single licenses/will match a single license/

Best regards,
Ulrich

Quoted 28 lines
documentation/migration-guides/migration-6.1.rst +21 -0
+   left-hand (license) side of a ``WITH`` expression. To allow a license with a
+   specific SPDX license exception, the SPDX license exception must be listed in
+   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
+
+   Practically speaking, the place where this comes up the most is when
+   attempting to exclude GPLv3 code using ``INCOMPATIBLE_LICENSE``. Previously,
+   this would have allowed any ``GPLv3-with-exception`` license, since they
+   were bespoke licenses that did not match the ``GPL-3.0* LGPL-3.0*``
+   expansion. Now, however, the licenses will match because they are e.g.
+   ``GPL-3.0-or-later WITH exception``. As such, any exceptions to the GPLv3
+   that should be allowed must be listed in
+   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
+
+Currently, the older syntax for license expressions is still parsed and
+automatically converted to an SPDX License Expression, but a warning is issued
+when this occurs. This support will eventually be removed and the only valid
+values for these variables will be SPDX License Expressions.
+
 Removed recipes
 ---------------
 
@@ -93,3 +148,6 @@ Removed classes
 
 Miscellaneous changes
 ---------------------
+
+.. _SPDX License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/
+.. _SPDX License Identifier: https://spdx.org/licenses/
Signature · 4 lines
Pengutronix e.K.                           | Ulrich Ölmann               |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |
#2 lore raw
In reply to Joshua Watt

Hi,

Quoted 14 lines · Joshua Watt via lists.yoctoproject.org

The LICENSE variable is now required to be SPDX license expressions, so provide a migration guide to describe the changes required to integrate this change

---
 .../migration-guides/migration-6.1.rst        | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
documentation/migration-guides/migration-6.1.rst +0 -0
index 8786cd699..48777e16c 100644

documentation/migration-guides/migration-6.1.rst And:: · line 78

Quoted 4 lines
documentation/migration-guides/migration-6.1.rst +1 -0
@@ -75,6 +75,61 @@ And::
 
    oe.utils.any_distro_features("x y", ...) -> bb.utils.contains_any("DISTRO_FEATURES", "x y", ...)
 
+``LICENSE`` is now a SPDX License Expression

s/a/an/

documentation/migration-guides/migration-6.1.rst And:: · line 81

Quoted 3 lines
documentation/migration-guides/migration-6.1.rst +3 -0
+--------------------------------------------
+
+The ``LICENSE`` variable is now an `SPDX License Expression`_ instead of the

s/``LICENSE``/:term:LICENSE/

This applies for all the variables below.

Quoted 14 lines
documentation/migration-guides/migration-6.1.rst +14 -0
+custom license expressions that have been used historically.
+
+The changes required for the new expressions are as follows:
+1. The ``&`` operator is replaced with ``AND``
+
+2. The ``|`` operator is replaced with ``OR``
+
+3. Any license value which is not a valid `SPDX License Expression`_ is an
+   error.
+
+4. Custom (non `SPDX License Identifier`_) licenses are still allowed, as long
+   as they are prefixed with ``LicenseRef-``. The behavior of looking for the
+   license text in ``LICENSE_PATH`` (with or without the ``LicenseRef-``
+   prefix) or ``NO_GENERIC_LICENSE`` is unchanged, and may still be used.

documentation/migration-guides/migration-6.1.rst And:: · line 105

Quoted 10 lines
documentation/migration-guides/migration-6.1.rst +10 -0
+
+5. ``CLOSED`` as a license is deprecated and will issue a warning. This license
+   is effectively "no license" (usually meaning e.g. "All rights reserved"),
+   but a more precise definition is to provide some sort of actual license text
+   using a custom license. This provides a more consistent definition of the
+   license text, since the meaning of "no license" may vary by jurisdiction.
+   Keep in mind that you can still have a common license file in
+   ``LICENSE_PATH`` and refer to it with a ``LicenseRef-`` license. Note that
+   when you this, you will also need to provide a ``LIC_FILE_CHKSUM`` value to
+   point to your license file.

I see most of the CLOSED licenses in OE-Core have been replaced with MIT, but I also see "LicenseRef-PD" being used in other places. Maybe we could suggest using one of the other as a replacement?

Quoted 31 lines
documentation/migration-guides/migration-6.1.rst +27 -0
+
+6. The ``WITH`` operator should now be used to describe an exception to a
+   license, instead of a bespoke license identifier. For example, the old
+   bespoke license ``Apache-2.0-with-LLVM-exception`` would become
+   ``Apache-2.0 WITH LLVM-exception``.
+
+7. Because of the change to use ``WITH`` instead of bespoke licenses, there is
+   a change in how ``INCOMPATIBLE_LICENSE`` works. Anything listed in this
+   variable will match a single licenses (unchanged), but it will also match the
+   left-hand (license) side of a ``WITH`` expression. To allow a license with a
+   specific SPDX license exception, the SPDX license exception must be listed in
+   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
+
+   Practically speaking, the place where this comes up the most is when
+   attempting to exclude GPLv3 code using ``INCOMPATIBLE_LICENSE``. Previously,
+   this would have allowed any ``GPLv3-with-exception`` license, since they
+   were bespoke licenses that did not match the ``GPL-3.0* LGPL-3.0*``
+   expansion. Now, however, the licenses will match because they are e.g.
+   ``GPL-3.0-or-later WITH exception``. As such, any exceptions to the GPLv3
+   that should be allowed must be listed in
+   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
+
+Currently, the older syntax for license expressions is still parsed and
+automatically converted to an SPDX License Expression, but a warning is issued
+when this occurs. This support will eventually be removed and the only valid
+values for these variables will be SPDX License Expressions.
+
 Removed recipes
 ---------------
 

documentation/migration-guides/migration-6.1.rst Removed classes · line 153

Quoted 6 lines
documentation/migration-guides/migration-6.1.rst +3 -0
@@ -93,3 +148,6 @@ Removed classes
 
 Miscellaneous changes
 ---------------------
+
+.. _SPDX License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/
+.. _SPDX License Identifier: https://spdx.org/licenses/

Thanks!
Antonin

#3 lore raw

PATCH v2 1/1 migration-guide: Add guide for converting licenses

In reply to Joshua Watt

The LICENSE variable is now required to be SPDX license expressions, so provide a migration guide to describe the changes required to integrate this change

---
 .../migration-guides/migration-6.1.rst        | 69 +++++++++++++++++++
 documentation/ref-manual/terms.rst            |  8 +++
 2 files changed, 77 insertions(+)
documentation/migration-guides/migration-6.1.rst +69 -0
index 8786cd699..a49cca270 100644
@@ -75,6 +75,71 @@ And::
 
    oe.utils.any_distro_features("x y", ...) -> bb.utils.contains_any("DISTRO_FEATURES", "x y", ...)
 
+:term:`LICENSE` is now a :term:`SPDX License Expression`
+--------------------------------------------------------
+
+The :term:`LICENSE` variable is now a :term:`SPDX License Expression` instead
+of the custom license expressions that have been used historically.
+
+The changes required for the new expressions are as follows:
+
+1. The ``&`` operator is replaced with ``AND``
+
+2. The ``|`` operator is replaced with ``OR``
+
+3. Any license value which is not a valid :term:`SPDX License Expression` is an
+   error.
+
+4. Custom (non `SPDX License Identifier`_) licenses are still allowed, as long
+   as they are prefixed with ``LicenseRef-``. The behavior of looking for the
+   license text in :term:`LICENSE_PATH` (with or without the ``LicenseRef-``
+   prefix) or :term:`NO_GENERIC_LICENSE` is unchanged, and may still be used.
+
+5. ``CLOSED`` as a license is deprecated and will issue a warning. This license
+   is effectively "no license" (usually meaning e.g. "All rights reserved"),
+   but a more precise definition is to provide some sort of actual license text
+   using a custom license. This provides a more consistent definition of the
+   license text, since the meaning of "no license" may vary by jurisdiction.
+   Keep in mind that you can still have a common license file in
+   :term:`LICENSE_PATH` and refer to it with a ``LicenseRef-`` license. Note
+   that when you do this, you will also need to provide a
+   :term:`LIC_FILE_CHKSUM` value to point to your license file.
+
+6. The generic ``PD`` (Public Domain) license is no longer allowed (since it is
+   not a valid `SPDX License Identifier`_). Additionally, the meaning of
+   "Public Domain" varies by jurisdiction, so leaving the exact license text
+   unspecified is not recommended. Instead, either find a matching SPDX license
+   (The `SPDX License Check`_ website can be useful here), or use a
+   ``LicenseRef-`` with :term:`NO_GENERIC_LICENSE` to specify the actual
+   license text.
+
+7. The ``WITH`` operator should now be used to describe an exception to a
+   license, instead of a bespoke license identifier. For example, the old
+   bespoke license ``Apache-2.0-with-LLVM-exception`` would become
+   ``Apache-2.0 WITH LLVM-exception``. For a list of the valid license
+   exceptions, see `SPDX License Exception`_.
+
+8. Because of the change to use ``WITH`` instead of bespoke licenses, there is
+   a change in how :term:`INCOMPATIBLE_LICENSE` works. Anything listed in this
+   variable will match a single license (unchanged), but it will also match the
+   left-hand (license) side of a ``WITH`` expression. To allow a license with a
+   specific `SPDX License Exception`_, the SPDX license exception must be
+   listed in :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS`.
+
+   Practically speaking, the place where this comes up the most is when
+   attempting to exclude GPLv3 code using :term:`INCOMPATIBLE_LICENSE`.
+   Previously, this would have allowed any ``GPLv3-with-exception`` license,
+   since they were bespoke licenses that did not match the
+   ``GPL-3.0* LGPL-3.0*`` expansion. Now, however, the licenses will match
+   because they are e.g. ``GPL-3.0-or-later WITH exception``. As such, any
+   exceptions to the GPLv3 that should be allowed must be listed in
+   :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS`.
+
+Currently, the older syntax for license expressions is still parsed and
+automatically converted to a :term:`SPDX License Expression`, but a warning is
+issued when this occurs. This support will eventually be removed and the only
+valid values for these variables will be :term:`SPDX License Expression`.
+
 Removed recipes
 ---------------
 
@@ -93,3 +158,7 @@ Removed classes
 
 Miscellaneous changes
 ---------------------
+
+.. _SPDX License Identifier: https://spdx.org/licenses/
+.. _SPDX License Exception: https://spdx.org/licenses/exceptions-index.html
+.. _SPDX License Check: https://tools.spdx.org/app/check_license/
documentation/ref-manual/terms.rst +8 -0
index cbe7c88e6..a955792bd 100644
@@ -578,6 +578,14 @@ universal, the list includes them just in case:
       and the ":ref:`dev-manual/sbom:creating a software bill of materials`"
       section of the Development Tasks manual.
 
+   :term:`SPDX License Expression`
+      A :term:`SPDX` defined standard for expressing how one or more licenses
+      apply to a work.
+
+      The syntax for a SPDX License Expression is defined in the `SPDX
+      Specification
+      <https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/>`__.
+
    :term:`Sysroot`
       When cross-compiling, the target file system may be differently laid
       out and contain different things compared to the host system. The concept
Signature · 1 line
2.54.0
#4 lore raw

Hi,

Merged on master-next with:

documentation/migration-guides/migration-6.1.rst +1 -1
index a49cca270..025b8f709 100644
@@ -103,7 +103,7 @@ The changes required for the new expressions are as follows:
    Keep in mind that you can still have a common license file in
    :term:`LICENSE_PATH` and refer to it with a ``LicenseRef-`` license. Note
    that when you do this, you will also need to provide a
-   :term:`LIC_FILE_CHKSUM` value to point to your license file.
+   :term:`LIC_FILES_CHKSUM` value to point to your license file.
 
 6. The generic ``PD`` (Public Domain) license is no longer allowed (since it is
    not a valid `SPDX License Identifier`_). Additionally, the meaning of

Antonin