mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-27 05:27:21 +00:00
Release notes collection proposal.
This commit is contained in:
David McMahon
parent
98de58dd28
commit
f18600f86c
218
docs/proposals/release-notes.md
Normal file
218
docs/proposals/release-notes.md
Normal file
@ -0,0 +1,218 @@
|
|||||||
|
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||||
|
|
||||||
|
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||||
|
|
||||||
|
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
|
||||||
|
<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
|
||||||
|
|
||||||
|
If you are using a released version of Kubernetes, you should
|
||||||
|
refer to the docs that go with that version.
|
||||||
|
|
||||||
|
Documentation for other releases can be found at
|
||||||
|
[releases.k8s.io](http://releases.k8s.io).
|
||||||
|
</strong>
|
||||||
|
--
|
||||||
|
|
||||||
|
<!-- END STRIP_FOR_RELEASE -->
|
||||||
|
|
||||||
|
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||||
|
|
||||||
|
|
||||||
|
# Kubernetes Release Notes
|
||||||
|
|
||||||
|
[djmm@google.com](mailto:djmm@google.com)<BR>
|
||||||
|
Last Updated: 2016-3-25
|
||||||
|
|
||||||
|
<!-- BEGIN MUNGE: GENERATED_TOC -->
|
||||||
|
|
||||||
|
- [Kubernetes Release Notes](#kubernetes-release-notes)
|
||||||
|
- [Objective](#objective)
|
||||||
|
- [Background](#background)
|
||||||
|
- [The Problem](#the-problem)
|
||||||
|
- [The (general) Solution](#the-general-solution)
|
||||||
|
- [Then why not just list *every* change that was submitted, CHANGELOG-style?](#then-why-not-just-list-every-change-that-was-submitted-changelog-style)
|
||||||
|
- [Options](#options)
|
||||||
|
- [Collection Design](#collection-design)
|
||||||
|
- [Publishing Design](#publishing-design)
|
||||||
|
- [Location](#location)
|
||||||
|
- [Layout](#layout)
|
||||||
|
- [Alpha/Beta/Patch Releases](#alphabetapatch-releases)
|
||||||
|
- [Major/Minor Releases](#majorminor-releases)
|
||||||
|
- [Work estimates](#work-estimates)
|
||||||
|
- [Caveats / Considerations](#caveats--considerations)
|
||||||
|
|
||||||
|
<!-- END MUNGE: GENERATED_TOC -->
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
|
||||||
|
Define a process and design tooling for collecting, arranging and publishing
|
||||||
|
release notes for Kubernetes releases, automating as much of the process as
|
||||||
|
possible.
|
||||||
|
|
||||||
|
The goal is to introduce minor changes to the development workflow
|
||||||
|
in a way that is mostly frictionless and allows for the capture of release notes
|
||||||
|
as PRs are submitted to the repository.
|
||||||
|
|
||||||
|
This direct association of release notes to PRs captures the intention of
|
||||||
|
release visibility of the PR at the point an idea is submitted upstream.
|
||||||
|
The release notes can then be more easily collected and published when the
|
||||||
|
release is ready.
|
||||||
|
|
||||||
|
## Background
|
||||||
|
|
||||||
|
### The Problem
|
||||||
|
|
||||||
|
Release notes are often an afterthought and clarifying and finalizing them
|
||||||
|
is often left until the very last minute at the time the release is made.
|
||||||
|
This is usually long after the feature or bug fix was added and is no longer on
|
||||||
|
the mind of the author. Worse, the collecting and summarizing of the
|
||||||
|
release is often left to those who may know little or nothing about these
|
||||||
|
individual changes!
|
||||||
|
|
||||||
|
Writing and editing release notes at the end of the cycle can be a rushed,
|
||||||
|
interrupt-driven and often stressful process resulting in incomplete,
|
||||||
|
inconsistent release notes often with errors and omissions.
|
||||||
|
|
||||||
|
### The (general) Solution
|
||||||
|
|
||||||
|
Like most things in the development/release pipeline, the earlier you do it,
|
||||||
|
the easier it is for everyone and the better the outcome. Gather your release
|
||||||
|
notes earlier in the development cycle, at the time the features and fixes are
|
||||||
|
added.
|
||||||
|
|
||||||
|
#### Then why not just list *every* change that was submitted, CHANGELOG-style?
|
||||||
|
|
||||||
|
On larger projects like Kubernetes, showing every single change (PR) would mean
|
||||||
|
hundreds of entries. The goal is to highlight the major changes for a release.
|
||||||
|
|
||||||
|
## Options
|
||||||
|
|
||||||
|
1. Use of pre-commit and other local git hooks
|
||||||
|
* Experiments here using `prepare-commit-msg` and `commit-msg` git hook files
|
||||||
|
were promising but less than optimal due to the fact that they would
|
||||||
|
require input/confirmation with each commit and there may be multiple
|
||||||
|
commits in a push and eventual PR.
|
||||||
|
1. Use of [github templates](https://github.com/blog/2111-issue-and-pull-request-templates)
|
||||||
|
* Templates provide a great way to pre-fill PR comments, but there are no
|
||||||
|
server-side hooks available to parse and/or easily check the contents of
|
||||||
|
those templates to ensure that checkboxes were checked or forms were filled
|
||||||
|
in.
|
||||||
|
1. Use of labels enforced by mungers/bots
|
||||||
|
* We already make great use of mungers/bots to manage labels on PRs and it
|
||||||
|
fits very nicely in the existing workflow
|
||||||
|
|
||||||
|
## Collection Design
|
||||||
|
|
||||||
|
The munger/bot option fits most cleanly into the existing workflow.
|
||||||
|
|
||||||
|
The design will include:
|
||||||
|
|
||||||
|
1. New labels added to github: `release-note-none`, maybe others for new release note categories - see Layout section below
|
||||||
|
1. A [new munger](https://github.com/kubernetes/kubernetes/issues/23409) that will:
|
||||||
|
* Initiate a `release-note-needed` label on all new PRs
|
||||||
|
* Block merge by the submit queue on all PRs labeled as `release-note-needed`
|
||||||
|
* Auto-remove `release-note-needed` when one of the release-note-\* labels is added
|
||||||
|
* Special case for cherry-picked/branch PRs, release-note-none is not allowed
|
||||||
|
|
||||||
|
## Publishing Design
|
||||||
|
|
||||||
|
### Location
|
||||||
|
|
||||||
|
With v1.2.0, the release notes were moved from their previous [github releases](https://github.com/kubernetes/kubernetes/releases)
|
||||||
|
location to [CHANGELOG.md](../../CHANGELOG.md). Going forward this seems like a good plan.
|
||||||
|
Other projects do similarly.
|
||||||
|
|
||||||
|
The kuberntes.tar.gz download link is also displayed along with the release notes
|
||||||
|
in [CHANGELOG.md](../../CHANGELOG.md).
|
||||||
|
|
||||||
|
Is there any reason to continue publishing anything to github releases if
|
||||||
|
the complete release story is published in [CHANGELOG.md](../../CHANGELOG.md)?
|
||||||
|
|
||||||
|
### Layout
|
||||||
|
|
||||||
|
Different types of releases will generally have different requirements in
|
||||||
|
terms of layout. As expected, major releases like v1.2.0 are going
|
||||||
|
to require much more detail than the automated release notes will provide.
|
||||||
|
|
||||||
|
The idea is that these mechanisms will provide 100% of the release note
|
||||||
|
content for alpha, beta and most minor releases and bootstrap the content
|
||||||
|
with a release note 'template' for the authors of major releases like v1.2.0.
|
||||||
|
|
||||||
|
The authors can then collaborate and edit the higher level sections of the
|
||||||
|
release notes in a PR, updating [CHANGELOG.md](../../CHANGELOG.md) as needed.
|
||||||
|
|
||||||
|
v1.2.0 demonstrated the need, at least for major releases like v1.2.0, for
|
||||||
|
several sections in the published release notes.
|
||||||
|
In order to provide a basic layout for release notes in the future,
|
||||||
|
new releases can bootstrap [CHANGELOG.md](../../CHANGELOG.md) with the following template types:
|
||||||
|
|
||||||
|
#### Alpha/Beta/Patch Releases
|
||||||
|
|
||||||
|
These are automatically generated from `release-note*` labels, but can be modified as needed.
|
||||||
|
|
||||||
|
```
|
||||||
|
Action Required
|
||||||
|
* PR titles from the release-note-action-required label
|
||||||
|
|
||||||
|
Other notable changes
|
||||||
|
* PR titles from the release-note label
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Major/Minor Releases
|
||||||
|
|
||||||
|
```
|
||||||
|
Major Themes
|
||||||
|
* Add to or delete this section
|
||||||
|
|
||||||
|
Other notable improvements
|
||||||
|
* Add to or delete this section
|
||||||
|
|
||||||
|
Experimental Features
|
||||||
|
* Add to or delete this section
|
||||||
|
|
||||||
|
Action Required
|
||||||
|
* PR titles from the release-note-action-required label
|
||||||
|
|
||||||
|
Known Issues
|
||||||
|
* Add to or delete this section
|
||||||
|
|
||||||
|
Provider-specific Notes
|
||||||
|
* Add to or delete this section
|
||||||
|
|
||||||
|
Other notable changes
|
||||||
|
* PR titles from the release-note label
|
||||||
|
```
|
||||||
|
|
||||||
|
## Work estimates
|
||||||
|
|
||||||
|
* The [new munger](https://github.com/kubernetes/kubernetes/issues/23409)
|
||||||
|
* Owner: @eparis
|
||||||
|
* Time estimate: Mostly done
|
||||||
|
* Updates to the tool that collects, organizes, publishes and sends release
|
||||||
|
notifications.
|
||||||
|
* Owner: @david-mcmahon
|
||||||
|
* Time estimate: A few days
|
||||||
|
|
||||||
|
|
||||||
|
## Caveats / Considerations
|
||||||
|
|
||||||
|
* As part of the planning and development workflow how can we capture
|
||||||
|
release notes for bigger features?
|
||||||
|
[#23070](https://github.com/kubernetes/kubernetes/issues/23070)
|
||||||
|
* For now contributors should simply use the first PR that enables a new
|
||||||
|
feature by default. We'll revisit if this does not work well.
|
||||||
|
|
||||||
|
|
||||||
|
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||||
|
[]()
|
||||||
|
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||||
Loading…
Reference in New Issue
Block a user