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

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

Hi Antonin,

On 11/13/24 9:31 AM, Antonin Godard wrote:
> 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?
> 

That's correct, I had forgotten we generate all migration notes from the 
latest release, so using DISTRO_NAME_MINUS_ONE would make all migration 
notes point to the minus one of the latest release, not good.

>>> 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?
> 

We already autogenerate releases.rst which does list all major and minor 
releases based on existing tags.

We know from which tag(s) we started to have release-notes and migration 
files.

We could stop the generation of those files depending on the current tag 
we're building for, to prevent trying to include files that don't exist 
in older releases.

We could also do the same trick we do for Supported Release Manuals and 
Outdated Release Manuals and just link to the newer 
docs.yoctoproject.org/X.Y.Z/migration-guides/release-X.Y.html

Just ideas though :)

Cheers,
Quentin