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

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Quentin,

On Wed Nov 13, 2024 at 3:18 PM CET, Quentin Schulz wrote:
> 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.

Correct, and this is the only file out of the two added in this patch that
defines these labels so we may as well define none.

>> +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 :)

That's interesting and would be useful indeed!

> Cheers,
> Quentin

Thank you!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com