Merge pull request #20498 from timhoffm/doc-release-guide-release-notes

QuLogic · web-flow · commit b7d05919865f · 2021-07-08T18:35:02.000-04:00
Adapt the release guide to the new release notes structure
diff --git a/doc/api/next_api_changes.rst b/doc/api/next_api_changes.rst
@@ -5,17 +5,6 @@ Next API changes
 
 .. ifconfig:: releaselevel == 'dev'
 
-   .. note::
-
-      The list below is a table of contents of individual files from the
-      most recent :file:`api_changes_X.Y` folder.
-
-      When a release is made
-
-       - The include directive below should be changed to point to the new file
-         created in the previous step.
-
-
    .. toctree::
       :glob:
       :maxdepth: 1
diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst
@@ -101,27 +101,54 @@ When making major or minor releases, update the supported versions in the
 Security Policy in :file:`SECURITY.md`.  Commonly, this may be one or two
 previous minor releases, but is dependent on release managers.
 
-Update "What's new" and "API changes"
--------------------------------------
+Update release notes
+--------------------
 
-Before tagging major and minor releases, the "what's new" and "API changes"
-listings should be updated.  This is not needed for micro releases.
+What's new
+~~~~~~~~~~
 
-For the "what's new",
+*Only needed for major and minor releases. Bugfix releases should not have new
+features.*
 
- 1. copy the current content to a file in :file:`doc/users/prev_whats_new`
- 2. merge all of the files in :file:`doc/users/next_whats_new/` into
-    :file:`doc/users/whats_new.rst` and delete the individual files
- 3. comment out the next what's new glob at the top
+Merge the contents of all the files in :file:`doc/users/next_whats_new/`
+into a single file :file:`doc/users/prev_whats_new/whats_new_X.Y.0.rst`
+and delete the individual files.
 
-Similarly for the "API changes",
+API changes
+~~~~~~~~~~~
 
- 1. copy the current api changes to a file is :file:`doc/api/prev_api_changes`
- 2. merge all of the files in the most recent :file:`doc/api/next_api_changes`
-    into :file:`doc/api/api_changes.rst`
- 3. comment out the most recent API changes at the top.
+*Primarily needed for major and minor releases. We may sometimes have API
+changes in bugfix releases.*
 
-In both cases step 3 will have to be un-done right after the release.
+Merge the contents of all the files in :file:`doc/api/next_api_changes/`
+into a single file :file:`doc/api/prev_api_changes/api_changes_X.Y.Z.rst`
+and delete the individual files.
+
+Release notes TOC
+~~~~~~~~~~~~~~~~~
+
+Update :file:`doc/users/release_notes.rst`:
+
+- For major and minor releases add a new section
+
+  .. code:: rst
+
+     X.Y
+     ===
+     .. toctree::
+         :maxdepth: 1
+
+         prev_whats_new/whats_new_X.Y.0.rst
+         ../api/prev_api_changes/api_changes_X.Y.0.rst
+         prev_whats_new/github_stats_X.Y.0.rst
+
+- For bugfix releases add the GitHub stats and (if present) the API changes to
+  the existing X.Y section
+
+  .. code:: rst
+
+     ../api/prev_api_changes/api_changes_X.Y.Z.rst
+     prev_whats_new/github_stats_X.Y.Z.rst
 
 Verify that docs build
 ----------------------
diff --git a/doc/users/next_whats_new.rst b/doc/users/next_whats_new.rst
@@ -6,19 +6,6 @@ Next what's new?
 
 .. ifconfig:: releaselevel == 'dev'
 
-   .. note::
-
-      The list below is a table of contents of individual files from the
-      'next_whats_new' folder.
-
-      When a release is made
-
-       - All the files in 'next_whats_new/' should be moved to a single file in
-         'prev_whats_new/'.
-       - The include directive below should be changed to point to the new file
-         created in the previous step.
-
-
    .. toctree::
       :glob:
       :maxdepth: 1
