---
title: "Adding Release Notes"
weight: 12
description: |
  Guidance on providing release notes for changes made to the main Kubernetes
  project repo.
---

On the kubernetes/kubernetes repository, release notes are required for any pull
request with user-visible changes, this could mean:

##### - User facing, critical bug-fixes
##### - Notable feature additions
##### - Output format changes
##### - Deprecations or removals
##### - Metrics changes
##### - Dependency changes
##### - API changes

Release notes are one of the most important reference
points for users about to install or upgrade to a particular release of
Kubernetes.

## Does my pull request need a release note?

Any user-visible or operator-visible change qualifies for a release note. This
could be a:

- CLI change
- API change
- UI change
- configuration schema change
- behavioral change
- change in non-functional attributes such as efficiency or availability,
  availability of a new platform
- a warning about a deprecation
- fix of a previous _Known Issue_
- fix of a vulnerability (CVE)

No release notes are required for changes to:

- tests
- build infrastructure
- fixes of bugs which have not been released

## Contents of a Release Note

A release note needs a clear, concise description of the change. This includes:

1. an indicator if the pull request _Added_, _Changed_, _Fixed_, _Removed_,
   _Deprecated_ functionality or changed enhancement/feature maturity (alpha,
   beta, stable/GA)
2. an indicator if there is user _Action required_
3. the name of the affected API or configuration fields, CLI commands/flags or
   enhancement/feature
4. a link to relevant user documentation about the enhancement/feature

## Applying a Release Note

On the kubernetes/kubernetes repository, release notes are required for any pull request with  [user-visible changes](#--user-facing-critical-bug-fixes).


To meet this requirement, do one of the following:
- Add notes in the release notes block, or
- Update the release note label

If you don't add release notes in the pull request template, the `do-not-merge/release-note-label-needed` label is added to your pull request automatically after you create it. There are a few ways to update it.

To add a release-note section to the pull request description:

For pull requests with a release note:

    ```release-note
    Your release note here
    ```

For pull requests that require additional action from users switching to the new release, include the string "action required" (case insensitive) in the release note:

    ```release-note
    action required: your release note here
    ```

For pull requests that don't need to be mentioned at release time, use the `/release-note-none` Prow command to add the `release-note-none` label to the PR. You can also write the string "NONE" as a release note in your PR description:

    ```release-note
    NONE
    ```

Your release note should be written in clear and straightforward sentences. Most often, users aren't familiar with the technical details of your PR, so consider what they _need to know_ when you write your release note.

Some brief examples of release notes:

```
The deprecated flag --conntrack-max has been removed from kube-proxy. Users of this flag should switch to --conntrack-min and --conntrack-max-per-core instead. (#78399, @rikatz)

The --export flag for the kubectl get command, deprecated since v1.14, will be removed in v1.18.

Fixed a bug that prevents dry-run from being honored for the pod/eviction sub-resource. (#76969, @apelisse)
```

Pull Request titles and body comments can be modified at any time prior to the release to make them friendly for release notes.

The release notes team maintains a [template](https://github.com/kubernetes/sig-release/blob/master/release-team/role-handbooks/release-notes/relnotes-template.md) for Kubernetes Release notes that may help clarify whether or not your PR requires a release note. The most recent [Kubernetes Release notes](https://kubernetes.io/docs/setup/release/notes/) can also provide insight into the writing style for release notes.

Release notes apply to pull requests on the master branch. For patch release branches the automated cherry-pick pull requests process (see the [cherry-pick instructions](/contributors/devel/sig-release/cherry-picks.md)) should be followed.  That automation will pull release notes from the master branch PR from which the cherry-pick originated. On a rare occasion a pull request on a patch release branch is not a cherry-pick, but rather is targeted directly to the non-master branch and in this case, a `release-note-*` label is required for that non-master pull request.

## Reviewing Release Notes

Reviewing the release notes of a pull request should be a dedicated step in the
overall review process. It is necessary to rely on the same metrics as other
reviewers to be able to distinguish release notes which might need to be
rephrased.

As a guideline, a release notes entry needs to be rephrased if one of the
following cases apply:

- The release note does not communicate the full purpose of the change.
- The release note has no impact on any user.
- The release note is grammatically incorrect.

In any other case the release note should be fine.

## Related

* [Behind The Scenes: Kubernetes Release Notes Tips & Tricks - Mike Arpaia, Kolide (KubeCon 2018 Lightning Talk)](https://www.youtube.com/watch?v=n62oPohOyYs)
