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

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

[Antonin Godard]

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>
---
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:
+
+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
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..d03ed7a3b07936fc3c2d15177f350b5507ecb5d4
--- /dev/null
+++ b/documentation/migration-guides/release-notes-5.2.rst
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+.. |yocto-codename| replace:: walnascar
+.. |yocto-ver| replace:: 5.2
+
+Release notes for |yocto-ver| (|yocto-codename|)
+------------------------------------------------
+
+New Features / Enhancements in |yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Linux kernel 6.XXX, gcc 14.XXX, glibc 2.XXX, LLVM 18.1.XXX, and over XXX other
+   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 |yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Recipe License changes in |yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following corrections have been made to the :term:`LICENSE` values set by recipes:
+
+Security Fixes in |yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Recipe Upgrades in |yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Contributors to |yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Repositories / Downloads for Yocto-|yocto-ver|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

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

[Quentin Schulz]

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.

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

Cheers,
Quentin

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

[Antonin Godard]

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