Release tool improvements

[nawazkh]

This issue aims to track the improvements needed/done at release tool
Assuming this to be a long-term effort, this issue will be used as an epic and subsequent tasks will be created to track the changes.

Release Tool Improvements

Preview Give feedback

1. Fix grammatically incorrect plurals in the release notes tool #9009
   kind/bug triage/accepted +2
   
2. Release tool output should be alphabetically sorted irrespective of their upper/lower case #9010
   kind/bug triage/accepted +2
   
3. When there are multiples areas they should be well formatted i.e. [MULTIPLE_AREAS]provider/control-plane-kubeadm|provider/bootstrap-kubeadm should be changed to [MULTIPLE_AREAS]KCP/CAPBK
4. Persist fixups to Multiple Areas. Where a PR has multiple areas assigned signal that this is the correct and final state. This prevents needing to fix this up each time the release notes are generated. The end result should be that this PR is listed in the release notes without the [MULTIPLE_AREAS] tag. To illustrate - but not suggest a solution - this could be done by adding and area/fixed label which signals that a PRs areas are correct.
5. Deduplicate prefixes in release notes. Where the PR title already contains a prefix which is the same as its area, e.g. 🌱 test/e2e: improve logging for a detected rollout #8953 The prefix should be deduplicated
6. Capitalize titles in release notes. Where the PR title starts with a lower case letter - or starts with a lower case letter after other modifications have been made - it should be capitalized
7. Format dependencies to exclude multiple bumps in the same set of release notes. For Go dependencies there's a disussion in this thread: https://kubernetes.slack.com/archives/C8TSNPY4T/p1686045243091189. For Github actions and other dependencies an alternative solution will have to be found.

[killianmuldoon]

/triage accepted

I don't think there's any reason to open up seperate issues for each of these as they're quite small and multiple might be done in a single PR.

[nawazkh]

/triage accepted

I don't think there's any reason to open up separate issues for each of these as they're quite small and multiple might be done in a single PR.

Oops, sorry! I created a few already; did not see your reply here.
Feel free to manage the other issues, if you would like to close them out or keep it as is. :)

[g-gaston]

@nawazkh can we add another one to the list?

When there are multiple areas, areas should be replaces with a well formatted version of their current rendering
clustercachetracker|provider/control-plane-kubeadm|provider/bootstrap-kubeadm
To
ClusterCacheTracker/KCP/CAPBK.

[killianmuldoon]

When there are multiple areas, areas should be replaces with a well formatted version of their current rendering
clustercachetracker|provider/control-plane-kubeadm|provider/bootstrap-kubeadm

I think we have to be careful with this as these probably do need to be manually reviewed to be sure there aren't issues with the multiple areas added. Maybe we could add another marker to signal that multiple areas are okay for a given PR so we don't have to manually fix it up each time we generate the notes.

[g-gaston]

I think we have to be careful with this as these probably do need to be manually reviewed to be sure there aren't issues with the multiple areas added.

Yeah, for know I'm suggesting just making sure we do the provider/control-plane-kubeadm -> KCP replacement
Same overall format with MULTIPLE_AREAS[*]. So it will still need review but at least it's just about deciding what to keep and what don't, but the areas themselves are user friendly.

Maybe we could add another marker to signal that multiple areas are okay for a given PR so we don't have to manually fix it up each time we generate the notes.

Good point. I would suggest tackling this as a separate task. It seems we might need to introduce a new mechanism, so it's not as cheap as just doing the replacement and might need a bit more thought. Maybe we can revisit based on how frequent these are? Maybe they are rare and it's not worth the added complexity.

[killianmuldoon]

Yeah, for know I'm suggesting just making sure we do the provider/control-plane-kubeadm -> KCP replacement
Same overall format with MULTIPLE_AREAS[*]

That sounds perfect! Let me know if the task I added above captured what you want.

Maybe we can revisit based on how frequent these are? Maybe they are rare and it's not worth the added complexity.

Completely agreed - I'll add a generic task for this on this umbrella issue, but I think you're right that it's not very high priority.

[sbueringer]

Just posting here because it's related. Going forward let's please consider that the release note tool can also be used by non-core CAPI. I.e. we should be careful about hard-coding the cluster-api repo name or adding features (without flags) that don't make sense for other consumers (xref: #9018 (comment))

P.S. the area mapping is totally fine

[g-gaston]

Just posting here because it's related. Going forward let's please consider that the release note tool can also be used by non-core CAPI. I.e. we should be careful about hard-coding the cluster-api repo name or adding features (without flags) that don't make sense for other consumers (xref: #9018 (comment))

P.S. the area mapping is totally fine

Should we add a README to the folder stating this? Or any other way to document this goal that you see fit.

To be honest, I didn't know this was a goal of the tool. So I fear if we don't document it, someone else might come in the future without this background and make breaking changes again.

[sbueringer]

README sounds like a good idea.

To be honest I don't know if it was an explicit goal of whoever forked the kubebuilder release note tool initially :).

But I think it's reasonable, we just have to be aware of it and then we can write new features in a way that they either work generically or can be toggled

P.S. I'm mostly thinking about CAPI providers leveraging this tool as they are closely related

[killianmuldoon]

Let's also add this as a comment on main.go in the release notes tool as an additional hint as maintenance of this tool is likely to swap hands frequently with release team handovers.

I also wasn't aware that we were considering non-CAPI users of the tool, but it makes complete sense for providers at least.

[killianmuldoon]

After #9018 merges:

From comment:

we should add a task to #9008 to add a make tool target that builds the release-notes tool if not present and runs it with the expected args. We should also update this guidance in the release docs.

[sbueringer]

Just to share data. Currently used by 4 other providers (soon 5 with CAPV): https://cs.k8s.io/?q=sigs.k8s.io%2Fcluster-api%2Fhack%2Ftools%2Frelease&i=nope&files=&excludeFiles=&repos=

[killianmuldoon]

@kubernetes-sigs/cluster-api-release-team to make sure I captured all the issues we spoke about on today's call.

[g-gaston]

/close
this one in favor of #9104

[k8s-ci-robot]

@g-gaston: Closing this issue.

In response to this:

/close
this one in favor of #9104

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.