New release notes process and guidance

[bgrant0607]

Forked from kubernetes/enhancements#204 and other discussions.

We put our release notes here:
https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md

The original release-note mechanism design and release changelog template were described here:
https://github.com/kubernetes/community/blob/master/contributors/design-proposals/release-notes.md

A decision about whether a PR should generate a release note was made merge-blocking in the PR workflow, as described here:
https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#release-notes

We subsequently made it possible to both set the labels automatically from the PR template, if properly filled out, and created /release-note commands to enable non-maintainers to set the labels, as described here:

https://github.com/kubernetes/community/blob/master/contributors/devel/pull-request-commands.md#set-release-notes

We also subsequently developed the features repo and process, from which some of the release notes are created by hand, based on which features target the release.

It's clear that the release-note mechanism in the kubernetes repo is causing too much contributor friction, that most people don't know what deserves a release note (e.g., examples, tests, and build scripts shouldn't have release notes) or what would make a good release note, and that the features repo provides another potential mechanism for surfacing release notes.

** What is the purpose of release notes **

Release notes give our users a heads-up about what is coming when they install or upgrade to a particular release of Kubernetes.

They are not primarily for contributors to Kubernetes, who could look at the PRs associated with a particular git tag.

** What deserves a release note **

Any significant user- or admin-visible change. It could be an API change, a CLI change, a UI change, a configuration schema change, a behavioral change, a change in non-functional attributes such as efficiency or availability, availability of a new platform, advance warning about deprecation of a feature, etc.

Fixes of issues previously cited as Known Issues due to the breadth and/or severity of their impact also qualify, as do CVE fixes.

** What doesn't deserve a release note **

Not exhaustive:

• tests (e.g., Fix TestServiceAlloc flakes)
• examples
• build infrastructure
• fixes of unreleased bugs
• fixes of minor bugs
• ideally, incomplete/inaccessible features

** What should be in a release note **

• Clear, concise description of the change
  • Explicitly name affected API or configuration fields, CLI commands or flags, relevant feature, measured non-functional changes, etc., in user-visible terms (e.g., using json field names rather than Go field names)
  • State whether it was added, removed, changed, deprecated, advanced in maturity (alpha, beta, stable), etc.
  • Link to relevant user documentation about the feature or, if non-trivial actions are required, about the change itself (yes, docs shouldn't be an afterthought)
  • Make the information relevant to and actionable by admins or users, if necessary. (For example, Fix GCI mounter issue is not.)
• Appropriately categorized
  • Feature
  • Action required
  • Deprecation announcement
  • Other notable change, categorized by component or feature area (not by contributor concepts such as SIG or code repo)

We also need some way of reporting known issues left unaddressed in the release, and recommended versions of dependencies (e.g., etcd, container runtimes), along with their known issues.

cc @idvoretskyi @calebamiles @fejta @pwittrock

[bgrant0607]

It's also worth looking at:

https://github.com/linuxfoundation/cii-best-practices-badge/blob/master/doc/criteria.md#release_notes

The project MUST provide, in each release, release notes that are a human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be. The release notes MUST NOT be the raw output of a version control log (e.g., the "git log" command results are not release notes).

[idvoretskyi]

@bgrant0607 should it work for every release (including minor x.y.z) or major only (x.y.0)?

[xiangpengzhao]

@bgrant0607 @idvoretskyi does this issue make sense?

"Consider splitting CHANGELOG in separate files"
kubernetes/kubernetes#48985

[zhangxiaoyu-zidif]

I think one release should have its own changelog in a independent files.
We can create a dir for these changelog files. :)

[dchen1107]

I made the proposal on how to automate the release note in 1.7 release cycle at (Join [email protected] to get access):
https://docs.google.com/presentation/d/1f-Td0Fs1kR3rSWlYzR0EJ2PFgd8_R2srlE_O_vxwdlk/edit#slide=id.p

The initial discussion among the kubernetes community is here: https://groups.google.com/forum/#!topic/kubernetes-dev/NNnbHAhzuVI

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[cblecker]

/remove-lifecycle stale
/lifecycle frozen

[bgrant0607]

@calebamiles @jdumars Could we please find someone to document this?

[justaugustus]

Adding RT Release Notes peeps from 1.10, 1.11, 1.12 to provide additional color and maybe get a volunteer to document the process.

[justaugustus]

/assign @nickchase @qedrakmar @marpaia @dstrebel @onyiny-ang

[k8s-ci-robot]

@justaugustus: GitHub didn't allow me to assign the following users: qedrakmar, marpaia, dstrebel.

Note that only kubernetes members and repo collaborators can be assigned.

In response to this:

/assign @nickchase @qedrakmar @marpaia @dstrebel @onyiny-ang

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.

[marpaia]

/assign @marpaia

[justaugustus]

/unassign @onyiny-ang @nickchase @marpaia
/assign @saschagrunert
/milestone v1.18
/priority important-soon

[k8s-ci-robot]

@justaugustus: The provided milestone is not valid for this repository. Milestones in this repository: [August, Next]

Use /milestone clear to clear the milestone.

In response to this:

/unassign @onyiny-ang @nickchase @marpaia
/assign @saschagrunert
/milestone v1.18
/priority important-soon

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.

[mariantalla]

/cc

[saschagrunert]

A note from my brain: Beside writing a guideline/contributor checklist, we could also introduce some sort of assisted review process around in conjunction with the release notes team.

@mariantalla what do you think?

[saschagrunert]

I think a good first step is to bring these information into the contributors guide: #4274

[mrbobbytables]

Assigning other relnotes owners to for additional ack
/assign @jeefy @onyiny-ang @marpaia

@saschagrunert @jeefy @onyiny-ang @marpaia - Do you think this is good enough to be closed at this point?

[saschagrunert]

Assigning other relnotes owners to for additional ack
/assign @jeefy @onyiny-ang @marpaia

@saschagrunert @jeefy @onyiny-ang @marpaia - Do you think this is good enough to be closed at this point?

I think we're probably fine with #4274 and #4282 and I suggest to close this issue. 👍

[jeefy]

+1 to closing

…

On Tue, Mar 10, 2020 at 3:45 AM Sascha Grunert ***@***.***> wrote: Assigning other relnotes owners to for additional ack /assign @jeefy <https://github.com/jeefy> @onyiny-ang <https://github.com/onyiny-ang> @marpaia <https://github.com/marpaia> @saschagrunert <https://github.com/saschagrunert> @jeefy <https://github.com/jeefy> @onyiny-ang <https://github.com/onyiny-ang> @marpaia <https://github.com/marpaia> - Do you think this is good enough to be closed at this point? I think we're probably fine with #4274 <#4274> and #4282 <#4282> and I suggest in closing this issue. 👍 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#484?email_source=notifications&email_token=AAKUO6GQKDY37W32FPAYCSDRGXV3JA5CNFSM4DFMMD2KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEOKLKUA#issuecomment-596948304>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKUO6HJIRZXZPXGFY5DFV3RGXV3JANCNFSM4DFMMD2A> .

[mrbobbytables]

with 2 acks, I'm going to go ahead and close this out. Thanks!

/close

[k8s-ci-robot]

@mrbobbytables: Closing this issue.

In response to this:

with 2 acks, I'm going to go ahead and close this out. Thanks!

/close

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.