Re: [yocto-docs PATCH v2] migration-guides: add placeholder files for next release

[Quentin Schulz <quentin.schulz@cherry.de>]

Hi Antonin,

On 11/13/24 2:43 PM, Antonin Godard wrote:
> Placeholder files for release 5.2 (Walnascar): migration guide and
> release notes.
> 
> Define two substitutions |yocto-ver| and |yocto-codename| to avoid
> mistakes in the document. Note that anchors cannot contain these so
> add a note on that in a comment.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

But see nits below :)

> ---
> Changes in v2:
> - Add the missing "release-5.2" document in documentation/migration-guides/index.rst.
> - Define |yocto-ver| and |yocto-codename| in
>    release-note-5.2/migration-5.2 to re-use in the document (expect
>    anchors).
> - release-note-5.2: replace "over 300" by "over XXX"
> - Link to v1: https://lore.kernel.org/r/20241112-release-note-5-2-placeholders-v1-1-a15b66eae472@bootlin.com
> ---
>   documentation/migration-guides/index.rst           |  1 +
>   documentation/migration-guides/migration-5.2.rst   | 77 ++++++++++++++++++++++
>   documentation/migration-guides/release-5.2.rst     |  9 +++
>   .../migration-guides/release-notes-5.2.rst         | 65 ++++++++++++++++++
>   4 files changed, 152 insertions(+)
> 
> diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst
> index e9d7f7280931ea6e9b26276ee70a9f9d00004450..14127d56ff397a37e4f36a2e368abcb54eedb8a1 100644
> --- a/documentation/migration-guides/index.rst
> +++ b/documentation/migration-guides/index.rst
> @@ -12,6 +12,7 @@ to move to one release of the Yocto Project from the previous one.
>   .. toctree::
>   
>      migration-general
> +   release-5.2
>      release-5.1
>      release-5.0
>      release-4.3
> diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..c186f633d26853d8fdd45529f5f3364b79591df2
> --- /dev/null
> +++ b/documentation/migration-guides/migration-5.2.rst
> @@ -0,0 +1,77 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +.. |yocto-codename| replace:: walnascar
> +.. |yocto-ver| replace:: 5.2
> +.. Note: anchors id below cannot contain substitutions so replace them with the
> +   value of |yocto-ver| above.
> +
> +Release |yocto-ver| (|yocto-codename|)
> +======================================
> +
> +Migration notes for |yocto-ver| (|yocto-codename|)
> +--------------------------------------------------
> +
> +This section provides migration information for moving to the Yocto
> +Project |yocto-ver| Release (codename "|yocto-codename|") from the prior release.
> +
> +.. _migration-5.2-supported-kernel-versions:
> +

Considering that we autolabel sections, maybe it'd be simpler to just have

Supported kernel versions in |yocto-ver|

here?

Or I think we could even do:

:ref:`migration-guides/migration-X.Y.Z:Supported kernel versions`

whenever we need to link to it?

This would allow to not need explicit and unique labels in the files.

> +Supported kernel versions
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The :term:`OLDEST_KERNEL` setting is XXX in this release, meaning that
> +out the box, older kernels are not supported. See :ref:`4.3 migration notes
> +<migration-4.3-supported-kernel-versions>` for details.
> +
[...]
> diff --git a/documentation/migration-guides/release-5.2.rst b/documentation/migration-guides/release-5.2.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..5c39b99e037e0a84ad6603d22ec4fb4dc2bf96ea
> --- /dev/null
> +++ b/documentation/migration-guides/release-5.2.rst
> @@ -0,0 +1,9 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +Release 5.2 (walnascar)
> +=======================
> +
> +.. toctree::
> +

If we could control how :glob: order the files, we could simply have

.. toctree::
    :glob:

    migration-5.2
    release-notes-5.2*

but this doesn't order the way we want, e.g. for kirkstone:
- release-notes-4.1
- release-notes-4.10
- release-notes-4.11
[...]
- release-notes-4.2
- release-notes-4.21
...

We could write an extension for the toctree, but eh :)

Cheers,
Quentin