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

Quentin Schulz
2024-11-13T09:22:50Z

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