Sort release notes by Kind(s) instead of SIG(s)

[saschagrunert]

This is a short demo how it looks like if we sort the release notes by its kind instead of the SIG.

For example:

> go run cmd/release-notes/main.go --start-rev v1.16.0 --end-rev v1.17.0

https://gist.github.com/saschagrunert/3eaf2d16b3f845fa69cf7a6661d81b05

[tpepper]

This form is definitely interesting. I wonder if it could be visually simplified still. Having every other line be "Courtesy of ..." is a bit visually distracting. Maybe if each stanza were more like:

-<p>Graduate ScheduleDaemonSetPods to GA. (feature gate will be removed in 1.18) action required. (<a href="https://github.com/kubernetes/kubernetes/pull/82795">#82795</a>, <a href="https://github.com/draveness">@draveness</a>)</p>
-<p>Courtesy of SIG Apps, SIG Scheduling, and SIG Testing</p>
+<p>Graduate ScheduleDaemonSetPods to GA. (feature gate will be removed in 1.18) action required. (<a href="https://github.com/kubernetes/kubernetes/pull/82795">#82795</a>, <a href="https://github.com/draveness">@draveness</a>, SIGs Apps, Scheduling, and Testing</p>

That removes 50 lines only though. And the results are still MANY MANY pages.

[saschagrunert]

Alright, I tried to improve the density and removed some unnecessary categorization, now it looks like this (--start-rev v1.16.0 --end-rev master):

https://gist.github.com/saschagrunert/baf7cb9114d7a58e6728592fac3659ed

[saschagrunert]

/retest

[jeefy]

/retest

[saschagrunert]

@jeefy do you think this format makes sense and is better than the current one?

[jeefy]

I like the readability of it better, but I also think we should somehow identify what sigs the PRs come from.

Also the API Changes section is based on things with kind/api-change so really that label should be ignored under "Other Changes"

[saschagrunert]

I like the readability of it better, but I also think we should somehow identify what sigs the PRs come from.

Yeah I agree, so for the markdown we could always add the SIG to every entry. Which would look like this (current state demo of v1.17.0-beta.0 to v1.17.0-beta.1):
https://gist.github.com/saschagrunert/a7c13d8b3e6a45d5c0f0c8f9da1e004b

Also the API Changes section is based on things with kind/api-change so really that label should be ignored under "Other Changes"
It behaves now like this, the only section treated as something special is New Features (see demo link above)

[jeefy]

I'm good with that! :)

/lgtm

@saschagrunert Unhold when you're ready.

[justaugustus]

Explicit hold for consensus check with the community.
I'll draft something later.
/hold

[saschagrunert]

I did some fine-adjustments regarding notes having multiple kinds. I also prettify the kind list that they have some sort of Title Case. Updated the first comment to contain the latest demo version.

[justaugustus]

@saschagrunert -- This is really awesome! One thing I think I'd like to see here is an idea of ranking the kind labels...

Some thoughts:

• We recently introduced kind/deprecation. I'd expected deprecation notices to be presented at the top.
• API Changes would probably come next
• New features
• ...

When two kind labels are applied, it'd be cool for the one of higher rank to contain the release note e.g., deprecation has higher rank than a cleanup, so the note would land in the "deprecation" section.

It's probably fine to do that as a follow-up though, if we think this is a good idea.

Sent a note to k-dev: https://groups.google.com/d/topic/kubernetes-dev/xwFKQfRWmAc/discussion

We'll merge this Thursday EOD PT, barring any strong objections.
Feel free to lift the hold then.

/lgtm
/approve

[qnetter]

Much more useful, to me.

[cartyc]

Awesome work @saschagrunert , looks great!

[onlydole]

SO much better for sure! Thank you for all the hard work, @saschagrunert!

[jeremyrickard]

I think this looks really great @saschagrunert!

I also really like @justaugustus's suggestion that kind/deprecation stuff should be at the top.

+1 from me

[rikatz]

+1 on moving Deprecation and maybe Breaking Changes to the top.

Amazing job btw :)

[sftim]

Does it make sense to label this for SIG Docs as well as SIG Release?
(because the release notes are part of the documentation)

[saschagrunert]

Some thoughts:

• We recently introduced kind/deprecation. I'd expected deprecation notices to be presented at the top.
• API Changes would probably come next
• New features
• ...

I added another commit on top of the recent changes, which sort the kinds by their priority.

When two kind labels are applied, it'd be cool for the one of higher rank to contain the release note e.g., deprecation has higher rank than a cleanup, so the note would land in the "deprecation" section.

It's probably fine to do that as a follow-up though, if we think this is a good idea.

I really like that idea and think it would result in a more clean document. So this is part of the latest commit as well. :)

The output of:

> go run cmd/release-notes/main.go --start-rev v1.16.0 --end-rev v1.17.0

now looks like this:
https://gist.github.com/saschagrunert/016041cfe4754f185fb7598e35ad6823
compared to the previous version:
https://gist.github.com/saschagrunert/80385c331a7e97ee408ce4f718594c5a

[liggitt]

I think this provides a much better starting point for our release notes than the current generator. Just a couple thoughts:

• I'm not sure bug/cleanup/flake are meaningful to end-users... I would probably bucket them together.
• I think sub-categorization by component is more meaningful to end-users (e.g. changes related to apiserver, scheduler, kubelet, kubectl, kubeadm, etc). I don't think we have sufficient information in the PRs to definitively attribute a PR to a component, so that might be a secondary step for now, but that would help organize some of the massive sections

[neolit123]

the area labels can be used for partial component distinction. they are applied automatically from OWNERS files.
area/{apiserver|kubectl|kubelet|kubeadm}

we don't have labels for controller-manager and scheduler.

[saschagrunert]

• I'm not sure bug/cleanup/flake are meaningful to end-users... I would probably bucket them together.

Okay, I added an option to map kinds, which for now maps bug, cleanup and flake into Other (Bug, Cleanup or Flake).

• I think sub-categorization by component is more meaningful to end-users (e.g. changes related to apiserver, scheduler, kubelet, kubectl, kubeadm, etc). I don't think we have sufficient information in the PRs to definitively attribute a PR to a component, so that might be a secondary step for now, but that would help organize some of the massive sections

Yes we could do that as a follow up I guess.

I re-generated the notes in the top comment to visualize the latest changes.

[evillgenius75]

I think this looks great. @saschagrunert, Is this also going to drive changes to the existing Release Note template we currently manually curate before Release day as that template still organizes by SIG in most cases?

I would prefer to see if we can do this all in one shot with just some final prettying of the MD to release.

https://github.com/kubernetes/sig-release/blob/master/release-team/role-handbooks/release-notes/relnotes-template.md

[saschagrunert]

I think this looks great. @saschagrunert, Is this also going to drive changes to the existing Release Note template we currently manually curate before Release day as that template still organizes by SIG in most cases?

I would prefer to see if we can do this all in one shot with just some final prettying of the MD to release.

https://github.com/kubernetes/sig-release/blob/master/release-team/role-handbooks/release-notes/relnotes-template.md

Oh yes, we should update that template as well in my point of view. We could apply the priority of kinds there too and maybe drop the distinction between “Notable” and “Other” changes. 🤔

[puerco]

@saschagrunert will the format change affect relnotes.k8s.io?

[justaugustus]

We'll merge this Thursday EOD PT, barring any strong objections.
Feel free to lift the hold then.

Hearing no objections, let's get this merged!
/lgtm
/approve
/hold cancel
/sig docs

@saschagrunert -- Thank you again for your great work on this!
Please capture the review suggestions as a follow up issue.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jeefy, justaugustus, saschagrunert

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• pkg/notes/OWNERS [jeefy,justaugustus,saschagrunert]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[saschagrunert]

@saschagrunert will the format change affect relnotes.k8s.io?

No :)