You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contributors/guide/release-notes.md
+81-44Lines changed: 81 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,20 +6,19 @@ description: |
6
6
project repo.
7
7
---
8
8
9
-
On the kubernetes/kubernetes repository, release notes are required for any pull
10
-
request with user-visible changes, this could mean:
9
+
On the [kubernetes/kubernetes repository][kubernetes-repository], release notes
10
+
are required for any pull request with user-visible changes, this could mean:
11
11
12
-
##### - User facing, critical bug-fixes
13
-
##### - Notable feature additions
14
-
##### - Output format changes
15
-
##### - Deprecations or removals
16
-
##### - Metrics changes
17
-
##### - Dependency changes
18
-
##### - API changes
12
+
- User facing, critical bug-fixes
13
+
- Notable feature additions
14
+
- Output format changes
15
+
- Deprecations or removals
16
+
- Metrics changes
17
+
- Dependency changes
18
+
- API changes
19
19
20
-
Release notes are one of the most important reference
21
-
points for users about to install or upgrade to a particular release of
22
-
Kubernetes.
20
+
Release notes are one of the most important reference points for users about to
21
+
install or upgrade to a particular release of Kubernetes.
23
22
24
23
## Does my pull request need a release note?
25
24
@@ -37,56 +36,78 @@ could be a:
37
36
- fix of a previous _Known Issue_
38
37
- fix of a vulnerability (CVE)
39
38
40
-
No release notes are required for changes to:
39
+
No release notes are required for changes to the following:
41
40
42
-
-tests
43
-
-build infrastructure
44
-
-fixes of bugs which have not been released
41
+
-Tests
42
+
-Build infrastructure
43
+
-Fixes for unreleased bugs
45
44
46
45
## Contents of a Release Note
47
46
48
47
A release note needs a clear, concise description of the change. This includes:
49
48
50
-
1.an indicator if the pull request _Added_, _Changed_, _Fixed_, _Removed_,
49
+
1.An indicator if the pull request _Added_, _Changed_, _Fixed_, _Removed_,
51
50
_Deprecated_ functionality or changed enhancement/feature maturity (alpha,
52
51
beta, stable/GA)
53
-
2.an indicator if there is user _Action required_
54
-
3.the name of the affected API or configuration fields, CLI commands/flags or
52
+
2.An indicator if there is user _Action required_
53
+
3.The name of the affected API or configuration fields, CLI commands/flags or
55
54
enhancement/feature
56
-
4.a link to relevant user documentation about the enhancement/feature
55
+
4.A link to relevant user documentation about the enhancement/feature
57
56
58
-
## Applying a Release Note
57
+
## Writing Good Release Notes
58
+
59
+
Good release notes can make a huge difference to the end user. To make sure that
60
+
your release notes are of the highest possible quality, follow these guidelines.
61
+
62
+
- Write your release notes in the past tense. For example, use "Added" instead
63
+
of "Add", "Fixed" instead of "Fix", and "Updated" instead of "Update".
64
+
- Include a call to action if there is anything the end user needs to do, along
65
+
with a link to a blog post or documentation item to provide better context.
66
+
- Keep your release notes relevant to the end user.
67
+
- Use Markdown to add links and emphasis, to make your release notes more
68
+
readable and usable.
69
+
- Use good grammar and make sure you capitalize the first word of each
70
+
sentence.
59
71
60
-
On the kubernetes/kubernetes repository, release notes are required for any pull request with [user-visible changes](#--user-facing-critical-bug-fixes).
72
+
Here are some pull requests with examples of exemplary release notes:
For more tips on writing good release notes, check out the [Release Notes Handbook][].
77
+
78
+
## Applying a Release Note
61
79
80
+
On the `kubernetes/kubernetes` repository, release notes are required for any pull
81
+
request with user-visible changes.
62
82
63
83
To meet this requirement, do one of the following:
64
84
- Add notes in the release notes block, or
65
85
- Update the release note label
66
86
67
-
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.
87
+
If you don't add release notes in the pull request template, the
88
+
`do-not-merge/release-note-label-needed` label is added to your pull request
89
+
automatically after you create it. There are a few ways to update it.
68
90
69
-
To add a release-note section to the pull request description:
91
+
To add a release-note section to the pull request description, add your release
92
+
note beneath the question *Does this PR introduce a user-facing change?*
70
93
71
-
For pull requests with a release note:
94
+
For pull requests that require additional action from users switching to the new
95
+
release, include the string "action required" (case insensitive) in the release
96
+
note.
72
97
73
-
```release-note
74
-
Your release note here
75
-
```
98
+
For an example, see [this pull request](https://github.com/kubernetes/kubernetes/pull/107207).
76
99
77
-
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:
100
+
For pull requests that don't need to be mentioned at release time, use the
101
+
`/release-note-none` Prow command to add the `release-note-none` label to the
102
+
PR. You can also write the string "NONE" as a release note in your PR
103
+
description.
78
104
79
-
```release-note
80
-
action required: your release note here
81
-
```
105
+
For an example of a pull request without release notes,
106
+
[take a look at this pull request](https://github.com/kubernetes/kubernetes/pull/107910).
82
107
83
-
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:
84
-
85
-
```release-note
86
-
NONE
87
-
```
88
-
89
-
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.
108
+
Your release note should be written in clear and straightforward sentences. Most
109
+
often, users aren't familiar with the technical details of your PR, so consider
110
+
what they _need to know_ when you write your release note.
90
111
91
112
Some brief examples of release notes:
92
113
@@ -98,11 +119,24 @@ The --export flag for the kubectl get command, deprecated since v1.14, will be r
98
119
Fixed a bug that prevents dry-run from being honored for the pod/eviction sub-resource. (#76969, @apelisse)
99
120
```
100
121
101
-
Pull Request titles and body comments can be modified at any time prior to the release to make them friendly for release notes.
102
-
103
-
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.
104
-
105
-
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.
122
+
Pull Request titles and body comments can be modified at any time prior to the
0 commit comments