Merge pull request #23315 from david-mcmahon/relnotes-proposal

docs/proposals/release-notes.md

+<!-- 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 -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/proposals/release-notes.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->