-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Release notes for users and provider implementers #8051
Comments
/triage accepted |
Joe and I discussed this shortly earlier today. I will try to summarize our discussion:
cc @kubernetes-sigs/cluster-api-release-team |
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). |
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:
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) |
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... |
Yup. Maybe a good compromise to start with the user part and only nudge for now for the providers part? |
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 |
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:
|
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.
Maybe. Do we know how k/k is dealing with this? |
/kind cleanup |
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:
The text was updated successfully, but these errors were encountered: