From f18600f86c7ef925e5f40803a394b5becb69d7f6 Mon Sep 17 00:00:00 2001 From: David McMahon Date: Mon, 21 Mar 2016 17:05:20 -0700 Subject: [PATCH] Release notes collection proposal. --- docs/proposals/release-notes.md | 218 ++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/proposals/release-notes.md diff --git a/docs/proposals/release-notes.md b/docs/proposals/release-notes.md new file mode 100644 index 00000000000..acc7c16b471 --- /dev/null +++ b/docs/proposals/release-notes.md @@ -0,0 +1,218 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +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). + +-- + + + + + + +# Kubernetes Release Notes + +[djmm@google.com](mailto:djmm@google.com)
+Last Updated: 2016-3-25 + + + +- [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) + + + +## 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. + + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/proposals/release-notes.md?pixel)]() +