Update release-notes.md with community feedback

This updates the release notes guide to meet style guidelines, as well
as including additional advice on release notes from community
feedback.

1 files changed, 81 insertions, 44 deletions

diff --git a/contributors/guide/release-notes.md b/contributors/guide/release-notes.md
index 2b3a5ef9..98a16c7d 100644
--- a/contributors/guide/release-notes.md
+++ b/contributors/guide/release-notes.md
@@ -6,20 +6,19 @@ description: |
   project repo.
 ---
 
-On the kubernetes/kubernetes repository, release notes are required for any pull
-request with user-visible changes, this could mean:
+On the [kubernetes/kubernetes repository][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
+- 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.
+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?
 
@@ -37,56 +36,78 @@ could be a:
 - fix of a previous _Known Issue_
 - fix of a vulnerability (CVE)
 
-No release notes are required for changes to:
+No release notes are required for changes to the following:
 
-- tests
-- build infrastructure
-- fixes of bugs which have not been released
+- Tests
+- Build infrastructure
+- Fixes for unreleased bugs
 
 ## 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_,
+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
+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
+4. A link to relevant user documentation about the enhancement/feature
 
-## Applying a Release Note
+## Writing Good Release Notes
+
+Good release notes can make a huge difference to the end user. To make sure that
+your release notes are of the highest possible quality, follow these guidelines.
+
+- Write your release notes in the past tense. For example, use "Added" instead
+  of "Add", "Fixed" instead of "Fix", and "Updated" instead of "Update".
+- Include a call to action if there is anything the end user needs to do, along
+  with a link to a blog post or documentation item to provide better context.
+- Keep your release notes relevant to the end user.
+- Use Markdown to add links and emphasis, to make your release notes more
+  readable and usable.
+- Use good grammar and make sure you capitalize the first word of each
+  sentence. 
 
-On the kubernetes/kubernetes repository, release notes are required for any pull request with  [user-visible changes](#--user-facing-critical-bug-fixes).
+Here are some pull requests with examples of exemplary release notes:
+- https://github.com/kubernetes/kubernetes/pull/97252
+- https://github.com/kubernetes/kubernetes/pull/105517
+
+For more tips on writing good release notes, check out the [Release Notes Handbook][].
+
+## Applying a Release Note
 
+On the `kubernetes/kubernetes` repository, release notes are required for any pull
+request with user-visible changes.
 
 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.
+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:
+To add a release-note section to the pull request description, add your release
+note beneath the question *Does this PR introduce a user-facing change?*
 
-For pull requests with a release note:
+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
-    Your release note here
-    ```
+For an example, see [this pull request](https://github.com/kubernetes/kubernetes/pull/107207).
 
-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:
+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
-    action required: your release note here
-    ```
+For an example of a pull request without release notes, 
+[take a look at this pull request](https://github.com/kubernetes/kubernetes/pull/107910).
 
-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.
+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:
 
@@ -98,11 +119,24 @@ The --export flag for the kubectl get command, deprecated since v1.14, will be r
 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.
+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
 
@@ -123,3 +157,6 @@ 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)
+
+[kubernetes-repository]: https://git.k8s.io/kubernetes/
+[Release Notes Handbook]: https://github.com/kubernetes/sig-release/tree/master/release-team/role-handbooks/release-notes