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

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

Hi Quentin,

On Tue Nov 12, 2024 at 6:15 PM CET, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Antonin,
>
[...]
>> +Migration notes for 5.2 (walnascar)
>> +-----------------------------------
>> +
>> +This section provides migration information for moving to the Yocto
>> +Project 5.2 Release (codename "walnascar") from the prior release.
>> +
>
> thought: By updating set_versions.py to include a DISTRO_NAME_MINUS_ONE 
> in poky.yaml, we could replace "from the prior release" with the name of 
> the release.
>
> Nothing for this patch though :)

But this would only be valid while Walnascar is the current, after that if
DISTRO_NAME_MINUS_ONE gets updated to Walnascar, this document would get the
wrong values, right?

Unless you meant using DISTRO_NAME_MINUS_ONE in other places in the doc?

[...]
>> 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::
>> +
>> +   migration-5.2
>> +   release-notes-5.2
>
> If this file is always the same, we can make set_versions.py or 
> something similar generate it.

It evolves when minor updates are published (5.0.1, 5.0.2, etc.), so we would
need to count the number of releases based on existing tags for a branch. We
would also need to exclude some of those for older releases (for instance the
kirkstone branch does not contain release-5.1.rst).

I'm not sure that the complexity is worth it?

>> diff --git a/documentation/migration-guides/release-notes-5.2.rst b/documentation/migration-guides/release-notes-5.2.rst
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..a6ba1e01a310111cf9483c74718315286b669821
>> --- /dev/null
>> +++ b/documentation/migration-guides/release-notes-5.2.rst
>> @@ -0,0 +1,62 @@
>> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
>> +
>> +Release notes for 5.2 (walnascar)
>> +---------------------------------
>> +
>> +New Features / Enhancements in 5.2
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +-  Linux kernel 6.XXX, gcc 14.XXX, glibc 2.XXX, LLVM 18.1.XXX, and over 300 other
>
> s/300/XXX/ ?

+1, thanks!

>> [...]
>> +Contributors to 5.2
>> +~~~~~~~~~~~~~~~~~~~
>> +
>> +Repositories / Downloads for Yocto-5.2
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> 
>
> thought: use rST substitutions to abstract even more out of this file 
> (easier to reuse for next next release :) ).
>
> Something like
>
> .. |yocto-ver| replace:: 5.2
>
> somewhere in the file and then
>
> Contributors to |yocto-ver|
>
> maybe?

Yes, this will avoid potential mistakes.

> This probably won't work for replacing text in the label though but we 
> don't seem to be using those in that file so maybe that's fine.
>
> Not tested.
>
> Looks good aside from the "300" I highlighted above, we probably will
> forget about it if we let the number be 300 and not XXX :)
>
> Cheers,
> Quentin

Thank you!
Antonin

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