manuals: document SPDX_CUSTOM_ANNOTATION_VARS

(From yocto-docs rev: 5811f4eb3e73aa5f8ca90e40ec6559a6d4d58fa3)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Saul Wold <Saul.Wold@windriver.com>
CC: Joshua Watt <JPEWhacker@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 75 insertions, 0 deletions

diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst
index 448c071c55..f51d08f84d 100644
--- a/documentation/dev-manual/sbom.rst
+++ b/documentation/dev-manual/sbom.rst
@@ -63,6 +63,9 @@ generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as:
    (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill
    "source code access" license requirements.
 
+See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows
+to associate custom notes to a recipe.
+
 See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX`
 project website for a list of tools to consume and transform the :term:`SPDX`
 data generated by the OpenEmbedded build system.
diff --git a/documentation/migration-guides/release-notes-4.2.rst b/documentation/migration-guides/release-notes-4.2.rst
index 04261244ff..6f7ff03e1b 100644
--- a/documentation/migration-guides/release-notes-4.2.rst
+++ b/documentation/migration-guides/release-notes-4.2.rst
@@ -8,6 +8,52 @@ New Features / Enhancements in 4.2
 
 -  Linux kernel 6.1, glibc 2.37 and ~350 other recipe upgrades
 
+-  Python 3.8 is the minimum Python version required on the build host.
+   For host distributions that do not provide it, this is included as part of the
+   :term:`buildtools` tarball.
+
+-  BitBake in this release now supports a new ``addpylib`` directive to enable
+   Python libraries within layers.
+
+   This directive should be added to your layer configuration
+   as in the below example from ``meta/conf/layer.conf``::
+
+      addpylib ${LAYERDIR}/lib oe
+
+-  BitBake has seen multiple internal changes that may impact
+   memory and disk usage as well as parsing time, in particular:
+
+   -  BitBake's Cooker server is now multithreaded.
+
+   -  BitBake's cache has been extended to include more hash
+      debugging data, but has also been optimized to :yocto_git:`compress
+      cache data <https://git.yoctoproject.org/poky/commit/?h=mickledore&id=7d010055e2af3294e17db862f42664ca689a9356>`.
+
+   -  BitBake's Cooker server :yocto_git:`can now be pinged
+      </poky/commit/?h=mickledore&id=26f255da09>`
+      from the UI.
+
+-  Architecture-specific enhancements:
+
+   -  This release adds initial support for the
+      :wikipedia:`LoongArch <Loongson#LoongArch>`
+      (``loongarch64``) architecture, though there is no testing for it yet.
+
+-  Kernel-related enhancements:
+
+-  QEMU/runqemu enhancements:
+
+-  Image-related enhancements:
+
+-  New variables:
+
+   -  :term:`VOLATILE_TMP_DIR` allows to specify
+      whether ``/tmp`` should be on persistent storage
+      or in RAM.
+
+   -  :term:`SPDX_CUSTOM_ANNOTATION_VARS` allows to add
+      specific comments to the :term:`SPDX` description of a recipe.
+
 -  Rust improvements:
 
    -  This release adds Cargo support on the target, and includes
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 29143caa3e..01b710199d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7578,6 +7578,32 @@ system and gives an overview of their function and contents.
       (+ 0.07\% with the tested image), compared to just enabling
       :term:`SPDX_INCLUDE_SOURCES`.
 
+   :term:`SPDX_CUSTOM_ANNOTATION_VARS`
+      This option allows to associate `SPDX annotations
+      <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe,
+      using the values of variables in the recipe::
+        
+         ANNOTATION1 = "First annotation for recipe"
+         ANNOTATION2 = "Second annotation for recipe"
+         SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2"
+
+      This will add a new block to the recipe ``.sdpx.json`` output::
+
+         "annotations": [
+           {
+             "annotationDate": "2023-04-18T08:32:12Z",
+             "annotationType": "OTHER",
+             "annotator": "Tool: oe-spdx-creator - 1.0",
+             "comment": "ANNOTATION1=First annotation for recipe"
+           },
+           {
+             "annotationDate": "2023-04-18T08:32:12Z",
+             "annotationType": "OTHER",
+             "annotator": "Tool: oe-spdx-creator - 1.0",
+             "comment": "ANNOTATION2=Second annotation for recipe"
+           }
+         ],
+
    :term:`SPDX_INCLUDE_SOURCES`
       This option allows to add a description of the source files used to build
       the host tools and the target packages, to the ``spdx.json`` files in