Update release process

docs/contribute/maintenance.rst

@@ -112,61 +112,66 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
         git checkout main
         git pull
 
-#.  When cutting any new release that you'll tag and want to be considered "stable" on either the ``main`` or development branch, update the Sphinx configuration file :file:`docs/conf.py` to match that version.
+#.  If you'll create a new *major* release, update :file:`.github/workflows/tests.yml` to include the new release branch in the list of branches that trigger the CI tests.
 
-    Hide the warning banner.
+    ..  code-block:: yaml
+        :emphasize-lines: 4
+
+        push:
+          branches:
+          - main
+          - 7.x
+          tags:
+          - v*
+
+    .. _hide-version-warning-banner:
+
+#.  Hide the version warning banner on the "stable" version on Read the Docs.
+    Update the Sphinx configuration file :file:`docs/conf.py`, which you'll commit and tag.
+    Then Read the Docs will recognize the highest version tag as the "stable" version.
+
+    ..  note::
+
+        Toward the end of this process, you'll revert this setting on ``main``, so that the "latest" version on Read the Docs continues to display the version warning banner.
 
     .. code-block:: python
 
         html_theme_options = {
             # ...
             "show_version_warning_banner": False,
 
-#.  Update the change log :file:`CHANGES.rst` with the change log entries in :file:`/news` with `towncrier <https://pypi.org/project/towncrier/>`_.
+#.  Update the change log :file:`CHANGES.rst` with the change log entries in :file:`/news` using `towncrier <https://pypi.org/project/towncrier/>`_.
 
     ..  code-block:: shell
 
         make changes
 
-#.  Create a commit on a ``release`` branch to release this version.
+#.  Add the changes, create a commit on the ``main`` branch, and push the changes to prepare a release of this version.
 
     .. code-block:: shell
 
-        git checkout -b release-$VERSION main
-        git checkout -b release-$VERSION main
-        git add CHANGES.rst docs/conf.py news/
-        git commit -m"version $VERSION"
+        git add CHANGES.rst news/
+        git add .github/workflows/tests.yml  # Only for a new major release
         git commit -m"version $VERSION"
+        git push  # to collective/icalendar
 
-#.  Push the commit and `create a pull request <https://github.com/collective/icalendar/compare?expand=1>`_.
-    Here is an `example pull request #457 <https://github.com/collective/icalendar/pull/457>`_.
-
-    .. code-block:: shell
-
-        git push -u origin release-$VERSION
-
-#.  See if the `CI tests <https://github.com/collective/icalendar/actions>`_ are running on the pull request.
+#.  See if the `CI tests <https://github.com/collective/icalendar/actions>`_ are running on the commit.
     If they are not running, no new release can be issued.
-    If the CI passes, merge the pull request.
-
-#.  Clean up behind you!
-
-    .. code-block:: shell
-
-        git checkout main
-        git pull
-        git branch -d release-$VERSION
-        git push -d origin release-$VERSION
+    If the CI passes, go ahead.
 
-#.  Create a tag for the release on its release branch ``*.x`` and see if the `CI tests`_ are running.
+#.  Create a tag for the release on its release branch ``*.x``, push, and make sure the `CI tests`_ are running.
 
     .. code-block:: shell
 
-        git checkout main
-        git pull
+        git checkout main  # You should already be on ``main``.
+        git pull  # In case someone else updated ``main`` while tests ran.
+        # For a major release, create a new branch and check it out.
+        git checkout -b 7.x
+        # For a minor or patch release, check out the existing branch.
         git checkout 7.x
+        git pull
         git merge main
-        git push upstream 7.x  # to collective/icalendar
+        git push  # to collective/icalendar
         git tag "v$VERSION"
         git push upstream "v$VERSION" # to collective/icalendar
 
@@ -185,29 +190,30 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
         tests: PyPI is waiting for your review
 
 #.  If the release is approved by a maintainer, it will be pushed to `PyPI`_.
+    Don't wait for that, continue.
 
-#.  Once the release is pushed to `PyPI`_, notify the issues mentioned on the new release of the new release.
-    Example:
+#.  Update the version switcher file :file:`docs/_static/version-switcher.json`.
 
-    .. code-block:: text
+    .. note::
 
-        This is included in v7.0.0.
+        This file is configured in :file:`docs/conf.py` on *all* branches to use the version on the ``main`` branch, which is "latest" on Read the Docs.
 
-#.  Update the version switcher file :file:`docs/_static/version-switcher.json`.
+        ..  code-block:: python
 
-    .. note::
+            json_url = "https://icalendar.readthedocs.io/en/latest/_static/version-switcher.json"
 
-        The remaining steps may be performed after the release because they pertain exclusively to documentation, which isn't included in the release.
-        The following examples were used for the 7.0.0 release.
+    The following examples were used for the 7.0.0 release.
+
+    a.  Check out the ``main`` branch and update it.
 
-    #.  When cutting a new *major release* version, checkout the ``main`` branch, and update :file:`docs/_static/version-switcher.json` to match that version.
-
         ..  code-block:: shell
-        
+
             git checkout main
             git pull
 
-        #.  Duplicate the second previous major version stanza and renumber it to the first previous version.
+    #.  When cutting a new *major* release version, update :file:`docs/_static/version-switcher.json` to match that version.
+
+        -   Duplicate the second previous major version stanza and renumber it to the first previous version.
             In other words, duplicate the ``5.x`` stanza, and renumber the copy to ``6.x``.
 
             .. code-block:: json
@@ -217,21 +223,28 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
                     "url": "https://icalendar.readthedocs.io/en/6.x/"
                 },
 
-        #.  Next, edit the array item for the previous version to reflect the current major release.
+        -   Next, edit the array item for the previous version to reflect the current major release.
+
+            .. vale off
 
             .. code-block:: json
+                :emphasize-lines: 2-3
 
                 {
                     "name": "7.x (stable)",
                     "version": "v7.0.0",
                     "url": "https://icalendar.readthedocs.io/en/stable/",
                     "preferred": "true"
                 },
-
 
-    #.  When cutting a *minor or patch release* version, on the ``main`` branch, update :file:`docs/_static/version-switcher.json` to match that version's tag name.
+            .. vale on
+
+    #.  When cutting a *minor* or *patch* release version, update :file:`docs/_static/version-switcher.json` to match that version's tag name.
+
+        .. vale off
 
         .. code-block:: json
+            :emphasize-lines: 2-3
 
             {
                 "name": "7.x (stable)",
@@ -240,32 +253,70 @@ However, only people with ``Environments/Configure PyPI`` access can approve an
                 "preferred": "true"
             },
 
-#.  When cutting a new *stable release* version, update the Sphinx configuration file :file:`docs/conf.py` as shown.
+        .. vale on
+
+    #.  For all releases, add, commit, and push the changes.
+
+        .. code-block:: shell
+
+            git add docs/_static/version-switcher.json
+            git commit -m "Update version switcher for $VERSION"
+            git push  # to collective/icalendar
+
+#.  Revert the change in the :ref:`earlier step <hide-version-warning-banner>` by updating the Sphinx configuration file :file:`docs/conf.py` to show the version warning banner on the ``main`` branch, which is "latest" on Read the Docs.
+
+    ..  code-block:: shell
+
+        git checkout main
+        git pull
+
+    ..  code-block:: python
+
+        html_theme_options = {
+            # ...
+            "show_version_warning_banner": True,
+
+    ..  code-block:: shell
+
+        git add docs/conf.py
+        git commit -m "Restore version warning banner for 'latest' on Read the Docs"
+        git push  # to collective/icalendar
 
-    #.  On the ``main`` branch, show the warning banner.
+#.  If you cut a new *major* release version, update the Sphinx configuration file :file:`docs/conf.py` on the *previous* numbered major release branch to show the version warning banner.
+    For example, when releasing 7.0.0, checkout ``6.x``, and update it as shown.
+
+    .. code-block:: shell
 
-        .. code-block:: python
+        git checkout 6.x
+        git pull
 
-            html_theme_options = {
-                # ...
-                "show_version_warning_banner": True,
+    .. code-block:: python
 
-    #.  On the previous numbered major release branch, show the warning banner.
-        For example, when releasing 7.0.0, checkout ``6.x``, and update it as shown.
+        html_theme_options = {
+            # ...
+            "show_version_warning_banner": True,
 
-        .. code-block:: python
+    ..  code-block:: shell
 
-            html_theme_options = {
-                # ...
-                "show_version_warning_banner": True,
+        git add docs/conf.py
+        git commit -m "Show version warning banner for previous major version 6.x on Read the Docs"
+        git push  # to collective/icalendar
 
 #.  Configure `Read the Docs <https://app.readthedocs.org/projects/icalendar/>`_.
 
-    #.  After a *minor release*, *patch release*, or an *unstable release*, deactivate previous releases in that release line.
+    a.  Verify that the "stable" version was activated automatically on Read the Docs.
+
+    #.  Deactivate previous releases in that current stable release line.
         Click on the ellipsis icon, and select :guilabel:`Configure version`.
         Toggle the :guilabel:`Active` switch to deactivate the version.
 
-    #.  After a *major release*, verify that the version was activated automatically on Read the Docs.
+
+#.  Add a comment to each of the issues mentioned in the new release of the new release.
+    Example:
+
+    .. code-block:: text
+
+        This is included in v7.0.0.
 
 
 Links

news/1293.documentation

@@ -0,0 +1 @@
+Updated release process documentation. @niccokunzmann @stevepiercy @SashankBhamidi