Release notes for users and provider implementers

[oscr]

One of the responsibilities of the comms release team is to: "Add docs to collect release notes for users and migration notes for provider implementers".

There was an interesting discussion on this topic in a pr so this is an attempt to move the discussion to a more appropriate place. Recommended background reading in #8015

@sbueringer wrote:

I think we're getting to an interesting point. Essentially we have two docs: one for provider authors one for users. And then we have the difference between those docs being in a draft state or final (or maybe we don't want to distinguish, but I definitely see a difference between the user doc where we would add notes over time and then the final release notes on the release).

So I think we might want a bigger discussions about:

* how do we collect information, e.g.
  
  * add them to docs as part of the PRs making the change
  * putting them in some way in the PR description so they can be automatically pulled from there

* where do we want to publish the final release notes:
  
  * on the GitHub release
  * in docs/CHANGELOG or CHANGELOG like Kubernetes (they then link from a release to the doc)
  * additionally in the book (?)

* how do we distinguish between draft and final state (aka how do we make it visible to our users if the notes are final or just a markdown where we collect information during a release)

* maybe provider and user docs should be just one doc?

[oscr]

/triage accepted

[oscr]

Joe and I discussed this shortly earlier today. I will try to summarize our discussion:

• From comms team point of view we would like to use the release notes script as much as possible. We are willing and interested in implementing additional features to reduce toil.

• In order to ensure the release notes are correct we think it’s best if the prs contain all the needed information to generate the notes. This will allow reviewers and approvers to validate the information and ensure it’s correct before merging the pr. Since this is done early there is less pressure during release to get this right. Comms will generate the release notes, read them and ensure they are not obviously wrong.

• We need to discuss both what are Users/Provider implementers are interested in and then how to classify the information. For example if we use emojis to indicate type of PR (bug, sparkles, etc) and a short prefix for the area (“clusterctl”, “api”, etc) a pr could look like this: :sparkles: clusterctl: Add move --to-directory and --from-directory flags. If we define what areas users/implementers are interested in we can generate two sets of release notes for each.

cc @kubernetes-sigs/cluster-api-release-team

[fabriziopandini]

In a separate thread, I already suggested using Kubernetes style release notes as a vehicle to add to PRs relevant notes to be added to the release notes, which matches your point above, so +1 from my side.

I'm also ok to extend the same approach to provider notes, adding some metadata as you are suggesting or simply having a handful of provider note types. However, in this case, I would suggest that we keep generating previews of provider notes during the entire release cycle because providers are used to peeking at the migration page on the main to get an idea of what is coming in the next release (we can use the same mechanism to create a preview of the release notes as well, but this has less priority than provider notes).

[sbueringer]

In general sounds fine to me.

I'm just not sure how good it will work to automatically generate something like our provider migration notes as a series of comments in PR descriptions. They often contain a lot of markdown and even code blocks. Also modifying them later would be only possible by the PR authors. The current approach seems simpler to me.

I think it's not that some PRs are relevant for users and others for provider authors. I think it's just different what we want to tell them:

• Users: here's a new feature, bugfix,...
• Provider authors: here's how you should migrate your provider to align with the changes in this PR

We can give it a try, but really not sure how good this will work for the provider doc.

Note: I think it would be nice if we could keep the provider doc as part of our book (independent of if we generate it or not)

[CecileRobertMichon]

Maybe a baby step would be to add a prompt in the PR template to nudge the author to edit the provider implementer guide doc (with a link) when something relevant is changing in the PR...

[sbueringer]

Yup. Maybe a good compromise to start with the user part and only nudge for now for the providers part?

[oscr]

I also like @CecileRobertMichon suggestion so lets give that a try.

From the comms team point of view we really want the third point asap. Having :emoji: area: Description for example :sparkles: clusterctl: Add move --to-directory and --from-directory flags. would make the release notes creation much easier. We're kind of guessing what area is when making the release notes. It would be better if they are encoded by the maintainers to ensure they are correct.

[oscr]

A related question: are there commits today in the release notes which we could summarize in the same way as docs? Can we improve the release notes by making them shorter?

For example:

• Proposals. They are not strictly related to the release so maybe they don't need it's own section for a specific release. These are many times presented during the office hours. I therefore suggest combining them with the "83 contributions to our documentation and book" summary.
• Project support cleanup: fixing hack scripts, formatting Makefiles, etc. In other words changes the user/implementer won't see. Maybe these could be summarized as ~"X project improvements"?

[sbueringer]

Proposals. They are not strictly related to the release so maybe they don't need it's own section for a specific release. These are many times presented during the office hours. I therefore suggest combining them with the "83 contributions to our documentation and book" summary.

A lot of folks (including users) never join the office hours, so we can't rely on them picking something up from office hours. I think a release is a good time to communicate which proposal were merged. If it's a problem to filter them out of the book category today we can have our own icon/category for proposals.

Project support cleanup: fixing hack scripts, formatting Makefiles, etc. In other words changes the user/implementer won't see. Maybe these could be summarized as ~"X project improvements"?

Maybe. Do we know how k/k is dealing with this?

[fabriziopandini]

/kind cleanup
/priority backlog