-
Notifications
You must be signed in to change notification settings - Fork 38.7k
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 proposal #23315
Merged
k8s-github-robot
merged 1 commit into
kubernetes:master
from
david-mcmahon:relnotes-proposal
Mar 30, 2016
Merged
Release Notes proposal #23315
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 --> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
They should probably go into the PR that enables the feature by default.