[PATCH] manuals: document SPDX_CUSTOM_ANNOTATION_VARS

[PATCH] manuals: document SPDX_CUSTOM_ANNOTATION_VARS

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Saul Wold <Saul.Wold@windriver.com>
CC: Joshua Watt <JPEWhacker@gmail.com>
---
 documentation/dev-manual/sbom.rst             |  3 +++
 .../migration-guides/release-notes-4.2.rst    |  9 ++++---
 documentation/ref-manual/variables.rst        | 26 +++++++++++++++++++
 3 files changed, 35 insertions(+), 3 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 4cf1974d4f..eb75dec6dc 100644
--- a/documentation/migration-guides/release-notes-4.2.rst
+++ b/documentation/migration-guides/release-notes-4.2.rst
@@ -45,9 +45,12 @@ New Features / Enhancements in 4.2
 
 -  New variables:
 
-   - :term:`VOLATILE_TMP_DIR` allows to specify
-     whether ``/tmp`` should be on persistent storage
-     or in RAM.
+   -  :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:
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 62f28bd278..26ed1f29ae 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7629,6 +7629,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"
+         ANNOTATION1 = "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
-- 
2.34.1

Re: [docs] [PATCH] manuals: document SPDX_CUSTOM_ANNOTATION_VARS

[Daniel Ammann]

On 4/18/23 11:09, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> CC: Saul Wold <Saul.Wold@windriver.com>
> CC: Joshua Watt <JPEWhacker@gmail.com>
> ---
>   documentation/dev-manual/sbom.rst             |  3 +++
>   .../migration-guides/release-notes-4.2.rst    |  9 ++++---
>   documentation/ref-manual/variables.rst        | 26 +++++++++++++++++++
>   3 files changed, 35 insertions(+), 3 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 4cf1974d4f..eb75dec6dc 100644
> --- a/documentation/migration-guides/release-notes-4.2.rst
> +++ b/documentation/migration-guides/release-notes-4.2.rst
> @@ -45,9 +45,12 @@ New Features / Enhancements in 4.2
>   
>   -  New variables:
>   
> -   - :term:`VOLATILE_TMP_DIR` allows to specify
> -     whether ``/tmp`` should be on persistent storage
> -     or in RAM.
> +   -  :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:
>   
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 62f28bd278..26ed1f29ae 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -7629,6 +7629,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"
> +         ANNOTATION1 = "Second annotation for recipe"
                       ^
I can't comment on the rest, but this seems to be a typo.

> +         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
> 
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#3841): https://lists.yoctoproject.org/g/docs/message/3841
> Mute This Topic: https://lists.yoctoproject.org/mt/98339958/3616718
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [daniel.ammann@bytesatwork.ch]
> -=-=-=-=-=-=-=-=-=-=-=-
> 

Re: [docs] [PATCH] manuals: document SPDX_CUSTOM_ANNOTATION_VARS

[Michael Opdenacker]

Hi Daniel,

Thanks for the review!

On 18.04.23 at 14:12, Daniel Ammann wrote:
>
>> +
>> +         ANNOTATION1 = "First annotation for recipe"
>> +         ANNOTATION1 = "Second annotation for recipe"


Oops, yes, good catch!
Fixed.
Many thanks.
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com