docs: improve release note instruction (#1157)

* docs: improve release note instruction

* chore: minor fixes for release note instructions.

Co-authored-by: Neil Conway <[email protected]>

.github/pull_request_template.md

@@ -1,15 +1,36 @@
 ## Description
 
+<!---
+Lead with the intended commit body in this description field. For breaking changes,
+please include "BREAKING CHANGE:" at the beginning of your commit body.
+At minimum, this section should include a bracketed reference to the Jira ticket,
+e.g. "[DET-1234]". When squash-and-merging, copy this directly into the description field.
+-->
 
 
 ## Test Plan
 
+<!---
+Describe the situations in which you've tested your change, and/or a screenshot as appropriate.
+Reviewers may ask questions of this test plan to ensure adequate manual coverage of changes.
+-->
 
 
 ## Commentary (optional)
 
+<!---
+Use this section of your description to add context to the PR. Could be for particularly
+tricky bits of code that could use extra scrutiny, historical context useful for reviewers, etc.
+You may intentionally leave this section blank and remove the title.
+--->
+
+
+## Checklist
+
+- [ ] User-facing API changes need the "User-facing API Change" label.
+- [ ] Release notes should be added as a separate file under `docs/release-notes/`.
+See [Release Note](../docs/release-notes/README.md) for details.
 
-<!-- User-facing API changes need the "User-facing API Change" label -->
 
 <!---
 ## Title
@@ -40,16 +61,4 @@ The first line should also:
 - contain a description that is at most 72 characters long
 - not end with sentence-ending punctuation
 - start (after the type) with a lowercase imperative ("add", "fix")
-
-## Description
-
-Lead with the intended commit body in this description field. For breaking changes, please include "BREAKING CHANGE:" at the beginning of your commit body. At minimum, this section should include a bracketed reference to the Jira ticket, e.g. "[DET-1234]". When squash-and-merging, copy this directly into the description field.
-
-## Test Plan
-
-Describe the situations in which you've tested your change, and/or a screenshot as appropriate. Reviewers may ask questions of this test plan to ensure adequate manual coverage of changes.
-
-## Commentary (optional)
-
-Use this section of your description to add context to the PR. Could be for particularly tricky bits of code that could use extra scrutiny, historical context useful for reviewers, etc. You may intentionally leave this section blank and remove the title.
---->
+-->

docs/release-notes/README.md

@@ -3,39 +3,48 @@
 We want release notes that are accurate, comprehensive, and written so that
 users of Determined can understand what has changed and what impact it has on
 their use of the product. We also want to spread out the work required to write
-high-quality release notes over time and across the members of the team, rather
-than writing all of the release notes at the last minute as part of cutting a
-new release.
+high-quality release notes over time and across the contributors to the project,
+rather than writing all of the release notes at the last minute as part of
+cutting a new release.
 
 ## How To Write Release Notes
 
 * Include an update to the release notes whenever you make a change that should
-  be communicated to users. That includes bug fixes, new features, and
-  improvements to existing features.
+  be communicated to users. That includes bug fixes, new features, changes to
+  previous behavior/APIs, and improvements to existing features.
 
 * Update the release notes as part of landing the change itself (e.g., in the
   same PR or as part of a chain of PRs to land a large feature). The author of
-  the PR has the most context about the change being made and any caveats or
-  additional context that users should be informed about. Reviewers should also
-  look at proposed release note changes as part of reviewing a PR.
+  the PR has the most context about the change being made and should be aware of
+  any caveats or additional context that users should be informed about.
+  Reviewers should also look at proposed release note changes as part of
+  reviewing a PR.
 
 * Write the release note entry as a separate file and add it to the
-  `docs/release-notes` directory. Name the file with the PR number as a
-  prefix. For example, `1097-nvidia-a100-support.txt`. The file should be in
-  reStructuredText format and consist of one or more list elements. Be sure to
-  highlight API changes and backward incompatibilities, discuss any steps that
-  must be taken to upgrade safely, and link to other locations in the
-  documentation as needed. For example:
-
-```
-- Add support for provisioning Nvidia A100 GPU instances on GCP.
-
-  - Running workloads on A100 chips currently requires building a custom task
-    environment with CUDA 11, because the default task environments provided by
-    Determined contain either CUDA 10.0 or CUDA 10.1. Refer to the
-    :ref:`custom-env` documentation for more details. The default task
-    environments will be upgraded to CUDA 11 in a future release of Determined.
-```
+  `docs/release-notes` directory.
+
+  * Name the file with the PR number as a prefix. For example, `1097-nvidia-a100-support.txt`.
+  * The file should be in reStructuredText format and should start with
+    `:orphan:` to avoid errors when building the docs.
+  * The file should contain one or more list elements, which should be
+    categorized into one of **New Features**, **Improvements**, **Bug Fixes**.
+  * Be sure to highlight API changes and backward incompatibilities with a prefix
+    "**Breaking Change:**", discuss any steps that must be taken to upgrade safely,
+    and link to other locations in the documentation as needed. For example:
+
+    ```
+    :orphan:
+
+    **New Features**
+
+    - Add support for provisioning Nvidia A100 GPU instances on GCP.
+
+      - Running workloads on A100 chips currently requires building a custom task
+        environment with CUDA 11, because the default task environments provided by
+        Determined contain either CUDA 10.0 or CUDA 10.1. Refer to the
+        :ref:`custom-env` documentation for more details. The default task
+        environments will be upgraded to CUDA 11 in a future release of Determined.
+    ```
 
 * As part of the release process, the release manager will merge these files
   together into `docs/release-notes.txt`, delete the individual files from