doc: releases: Clarify what belongs in relnotes vs migration

[carlescufi]

The intention of this commit is to clarify what belongs where, given that recent contributions have made it unclear.

[henrikbrixandersen]

I was hoping for more recommendations on what to put where, whether to link between the two files, etc.

At least a link and an introduction to the split of documentation at the very top of each release note file would be good. I am afraid users/developers will overlook the newly introduced migration guide otherwise.

[kartben]

Sorry that I, as the assignee, let this one go stale. I agree with @henrikbrixandersen.
Also, I think the current wording implies that any change requiring modifications/migration would only be described in the migration guide, which I think would be counterproductive and doesn't reflect how we'd want to do things.

See e.g commit ac520e6: it does have a short entry in the release notes describing something new and a related entry in the migration guide as this new features comes with some breaking changes, and I think that's the right thing to do.

Something like this?

Suggested change

	Release notes contain a list of changes that have been made to the different
	areas of the project during the development cycle of the release. Those do not
	include changes that require the user to modify their own application in order
	to upgrade to the release. Those instead belong in the corresponding migration
	document.
	Release notes contain a list of changes that have been made to the different
	areas of the project during the development cycle of the release.
	Changes that require the user to modify their own application to support the new
	release may be mentioned in the release notes, but the details regarding `what`
	needs to be changed are to be detailed the release's migration document.

[mbolivar-ampere]

@carlescufi

require the user to modify their own application

Doesn't this mean that the migration guide should only cover breaking changes, but not deprecations? I think deprecations belong in the migration guide too. As a user, I would certainly like to learn about them earlier rather than later.

I'm trying to sort out the differences for the devicetree API in particular. This is a bit of a special case, as you know. I think you are implying:

• new zephyr/devicetree.h macros go in the release notes
• new bindings go in the release notes
• new properties go in the release notes
• newly deprecated properties go in the release notes (again, this feels a bit anti-user to me)
• the following property changes go in the migration guide: removal, different cells in a specifier, different type, different const value, removal of some but not all enum elements, new default values, going from not required to required: true
• removed bindings go in the migration guide

TBH this partition between release notes and migration guide feels artificially fragmented to me.

Wouldn't it make more sense to include all the bindings changes in the release notes, but make special mention of the breaking changes in the migration guide?

[henrikbrixandersen]

@carlescufi ping

[carlescufi]

Architecture WG:

• @nashif says that whatever goes to the migration guide must be useful to anyone migrating.
• @henrikbrixandersen added only the new drivers/features in the release notes. In the migration guide the required changes
• @fabiobaltieri agrees to add new features only to the release notes
• @nashif suggests an editorial process at the end that cleans up the contents, removes excess contents and move content to the migration guide
• @kartben mentions that information is missing in some cases, which can be attributed to maintainers not completing the release notes in time

The following belongs in the migration guide and in the migration guide (Required Changes) ONLY :

• Changes in the code that require an action (i.e. a modification of the source code or configuration files) on the part of the user in order to keep the existing behavior of their application. This includes:

  • Breaking API changes

  • Deprecations

  • Devicetree or Kconfig changes that affect the user (changes to defaults, renames, etc)

  • Treewide changes that have an effect (eg. changing the include path or defaulting to a different C standard library)

  • Anything else that can affect the compilation or runtime behavior of an existing application

Remove the sections, and the recommended changes altogether.

[fabiobaltieri]

Maybe for the release notes we could just have

• Major enhancement (we already have it), single list, prob the same as the blog post
• Other new features by subsystem, pretty much new drivers or smaller features

Then the maintainer would have to keep the "major" list curated, for the subsystem if there's no significant change we'd just ask to list the new drivers, or nothing if there's none (which is probably pretty common).

For the template, we were kicking around the idea of adding some new metadata in the maintainers file. Maybe we could have a bit that says if the area should have a section in the release notes and migration notes templates, and then we could use that to generate the template automatically, as well as a checklist like #50423 to ask maintainers to add their section?

[mbolivar-ampere]

Can someone who was at the Arch WG confirm this impact on DT?

Release notes:

• new zephyr/devicetree.h macros
• new bindings
• new properties

Migration guide:

• removed bindings
• bindings property changes: deprecation, removal and other breaking changes [*]

The bindings parts of the release notes are partially automated, so I will update my script accordingly if this is the WG's conclusion.

[*] for the DT stans out there, a complete list is: different cells in a specifier, different type, different const value, removal of some but not all enum elements, new default values, going from not required to required: true

[nordicjm]

If fixes or changes are no longer going to go in release notes then there should be another page they go on. It's all fine and well to search through git logs but it's far easier to have a page where fixes for a particular release (that do not need modifications) are put which are grouped into sections as the current release notes page is, things like:

MCUmgr:

* Fixed an issue with UDP transport that would cause a buffer overflow if IPv6 networking is enabled by only the IPv4 MCUmgr transport was selected

* Fixed an issue...

Using github search is just not an option, try searching using terms for bugs you vaguely remember from 3 years ago, unless you match an exact term of the title and even then unless you go through 30+ pages of results, you're not going to find it.

[carlescufi]

Can someone who was at the Arch WG confirm this impact on DT?

Release notes:

• new zephyr/devicetree.h macros
• new bindings
• new properties

Migration guide:

• removed bindings
• bindings property changes: deprecation, removal and other breaking changes [*]

I can confirm this was the intent @mbolivar-ampere

[kartben]

Sorry that I, as the assignee, let this one go stale. I agree with @henrikbrixandersen.
Also, I think the current wording implies that any change requiring modifications/migration would only be described in the migration guide, which I think would be counterproductive and doesn't reflect how we'd want to do things.

See e.g commit ac520e6: it does have a short entry in the release notes describing something new and a related entry in the migration guide as this new features comes with some breaking changes, and I think that's the right thing to do.

Something like this?

Suggested change

	Release notes contain a list of changes that have been made to the different
	areas of the project during the development cycle of the release. Those do not
	include changes that require the user to modify their own application in order
	to upgrade to the release. Those instead belong in the corresponding migration
	document.
	Release notes contain a list of changes that have been made to the different
	areas of the project during the development cycle of the release.
	Changes that require the user to modify their own application to support the new
	release may be mentioned in the release notes, but the details regarding `what`
	needs to be changed are to be detailed the release's migration document.

[henrikbrixandersen]

This needs rebasing. Is the target milestone still v3.6.0?

[kartben]

@carlescufi could you help get this over the finish line so that we have better (albeit maybe not perfect) guidelines for the upcoming 3.6, as otherwise I fear we'll spend a lot of time repeating ourselves on various PRs to give people guidance

[carlescufi]

@carlescufi could you help get this over the finish line so that we have better (albeit maybe not perfect) guidelines for the upcoming 3.6, as otherwise I fear we'll spend a lot of time repeating ourselves on various PRs to give people guidance

@kartben yep, on it! Let's see if I can get it done today.

[carlescufi]

@henrikbrixandersen @kartben PTAL

[henrikbrixandersen]

Thanks!

[kartben]

Thank you, sir!
Spotted a typo (probably mine), and a small nit. Thanks!

[carlescufi]

@henrikbrixandersen @kartben PTAL

@henrikbrixandersen @fabiobaltieri once more please, just typo fixing
Also feel free to merge