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

Placeholder files for release 5.2 (Walnascar): migration guide and
release notes.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/migration-guides/migration-5.2.rst   | 72 ++++++++++++++++++++++
 documentation/migration-guides/release-5.2.rst     |  9 +++
 .../migration-guides/release-notes-5.2.rst         | 62 +++++++++++++++++++
 3 files changed, 143 insertions(+)


---
base-commit: 2849690abf94872e259e712128e90413f3b9a2f2
change-id: 20241112-release-note-5-2-placeholders-1f2bcea5677c

Best regards,

Hi Antonin,

On 11/12/24 5:52 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Placeholder files for release 5.2 (Walnascar): migration guide and
> release notes.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/migration-guides/migration-5.2.rst   | 72 ++++++++++++++++++++++
>   documentation/migration-guides/release-5.2.rst     |  9 +++
>   .../migration-guides/release-notes-5.2.rst         | 62 +++++++++++++++++++
>   3 files changed, 143 insertions(+)
> 
> diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..8a077b31f87582e0bcff7ca6fbf6f300c0274e6f
> --- /dev/null
> +++ b/documentation/migration-guides/migration-5.2.rst
> @@ -0,0 +1,72 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +Release 5.2 (walnascar)
> +=======================
> +
> +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 :)

> +.. _migration-5.2-supported-kernel-versions:
> +
> +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.
> +
> +.. _migration-5.2-supported-distributions:
> +
> +Supported distributions
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Compared to the previous releases, running BitBake is supported on new
> +GNU/Linux distributions:
> +
> +On the other hand, some earlier distributions are no longer supported:
> +
> +See :ref:`all supported distributions <system-requirements-supported-distros>`.
> +
> +.. _migration-5.2-go-changes:
> +
> +Go language changes
> +~~~~~~~~~~~~~~~~~~~
> +
> +.. _migration-5.2-systemd-changes:
> +
> +systemd changes
> +~~~~~~~~~~~~~~~
> +
> +.. _migration-5.2-recipe-changes:
> +
> +Recipe changes
> +~~~~~~~~~~~~~~
> +
> +.. _migration-5.2-removed-variables:
> +
> +Removed variables
> +~~~~~~~~~~~~~~~~~
> +
> +The following variables have been removed:
> +
> +.. _migration-5.2-removed-recipes:
> +
> +Removed recipes
> +~~~~~~~~~~~~~~~
> +
> +The following recipes have been removed in this release:
> +
> +.. _migration-5.2-removed-classes:
> +
> +Removed classes
> +~~~~~~~~~~~~~~~
> +
> +The following classes have been removed in this release:
> +
> +.. _migration-5.2-misc-changes:
> +
> +Miscellaneous changes
> +~~~~~~~~~~~~~~~~~~~~~
> 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.

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

> +   recipe upgrades.
> +
> +-  New variables:
> +
> +-  Kernel-related changes:
> +
> +-  New core recipes:
> +
> +-  QEMU / ``runqemu`` changes:
> +
> +-  Go changes:
> +
> +-  Rust changes:
> +
> +-  wic Image Creator changes:
> +
> +-  SDK-related changes:
> +
> +-  Testing-related changes:
> +
> +-  Utility script changes:
> +
> +-  BitBake changes:
> +
> +-  Packaging changes:
> +
> +-  Security changes:
> +
> +-  LLVM related changes:
> +
> +-  SPDX-related changes:
> +
> +-  Miscellaneous changes:
> +
> +Known Issues in 5.2
> +~~~~~~~~~~~~~~~~~~~
> +
> +Recipe License changes in 5.2
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The following corrections have been made to the :term:`LICENSE` values set by recipes:
> +
> +Security Fixes in 5.2
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Recipe Upgrades in 5.2
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +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?

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

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

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

On Wed Nov 13, 2024 at 10:22 AM CET, Quentin Schulz wrote:
> 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,
>>>
[...]
>>>> +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

I see, I'm taking a note, and I'll try to look into this at some point to see
what's worth automating or not. I know I also need to look into the releases.svg
autobuilder deployment, so maybe there's something to refactor here also.

In the meantime I'll send a v2 shortly with some improvements.

Thanks for your input and ideas!
Antonin