Re: [docs][PATCH] migration-guide: Add guide for converting licenses

Hi,

On Tue Jul 21, 2026 at 11:47 PM CEST, Joshua Watt via lists.yoctoproject.or=
g wrote:
> 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
>
> Signed-off-by: Joshua Watt <[email protected]>
> ---
>  .../migration-guides/migration-6.1.rst        | 58 +++++++++++++++++++
>  1 file changed, 58 insertions(+)
>
> diff --git a/documentation/migration-guides/migration-6.1.rst b/documenta=
tion/migration-guides/migration-6.1.rst
> index 8786cd699..48777e16c 100644
> --- a/documentation/migration-guides/migration-6.1.rst
> +++ b/documentation/migration-guides/migration-6.1.rst
> @@ -75,6 +75,61 @@ And::
> =20
>     oe.utils.any_distro_features("x y", ...) -> bb.utils.contains_any("DI=
STRO_FEATURES", "x y", ...)
> =20
> +``LICENSE`` is now a SPDX License Expression

s/a/an/

> +--------------------------------------------
> +
> +The ``LICENSE`` variable is now an `SPDX License Expression`_ instead of=
 the

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

This applies for all the variables below.

> +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, a=
s long
> +   as they are prefixed with ``LicenseRef-``. The behavior of looking fo=
r 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 reserve=
d"),
> +   but a more precise definition is to provide some sort of actual licen=
se text
> +   using a custom license. This provides a more consistent definition of=
 the
> +   license text, since the meaning of "no license" may vary by jurisdict=
ion.
> +   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`` va=
lue to
> +   point to your license file.

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

> +
> +6. The ``WITH`` operator should now be used to describe an exception to =
a
> +   license, instead of a bespoke license identifier. For example, the ol=
d
> +   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, th=
ere is
> +   a change in how ``INCOMPATIBLE_LICENSE`` works. Anything listed in th=
is
> +   variable will match a single licenses (unchanged), but it will also m=
atch 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 l=
isted in
> +   ``INCOMPATIBLE_LICENSE_EXCEPTIONS``.
> +
> +   Practically speaking, the place where this comes up the most is when
> +   attempting to exclude GPLv3 code using ``INCOMPATIBLE_LICENSE``. Prev=
iously,
> +   this would have allowed any ``GPLv3-with-exception`` license, since t=
hey
> +   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 G=
PLv3
> +   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 v=
alid
> +values for these variables will be SPDX License Expressions.
> +
>  Removed recipes
>  ---------------
> =20
> @@ -93,3 +148,6 @@ Removed classes
> =20
>  Miscellaneous changes
>  ---------------------
> +
> +.. _SPDX License Expression: https://spdx.github.io/spdx-spec/v3.0.1/ann=
exes/spdx-license-expressions/
> +.. _SPDX License Identifier: https://spdx.org/licenses/

Thanks!
Antonin