From 593136e62c85698e6b34d13cbe1412a11d6eb317 Mon Sep 17 00:00:00 2001
From: Sebastian Bank <sebastian.bank@uni-leipzig.de>
Date: Sun, 12 Dec 2021 11:51:37 +0100
Subject: [PATCH] improve release process steps, wording and formatting

---
 docs/release_process.rst | 45 ++++++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/docs/release_process.rst b/docs/release_process.rst
index a97e41d91a..c3f9e9fd38 100644
--- a/docs/release_process.rst
+++ b/docs/release_process.rst
@@ -5,13 +5,19 @@ Release process
 Build
 -----
 
+Update build dependencies:
+
+.. code:: bash
+
+    $ pip install -U setuptools wheel twine
+
 Create ``release`` branch from main:
 
 .. code:: bash
 
     $ git checkout -b release
 
-Cleanup (remove all untracked files and directories):
+**Cleanup** (remove all untracked files and directories):
 
 .. code:: bash
 
@@ -23,7 +29,7 @@ Update ``help()`` output:
 
     $ ./update-help.py
 
-Set release version (remove ``.dev0`` from ``$MAJOR.$MINOR[.$BUGFIX]``):
+Set **release version** (remove ``.dev0`` from ``$MAJOR.$MINOR[.$BUGFIX]`` version):
 
 - ``docs/conf.py``
 - ``graphviz/__init__.py``
@@ -31,9 +37,9 @@ Set release version (remove ``.dev0`` from ``$MAJOR.$MINOR[.$BUGFIX]``):
 
 Document release:
 
-- remove ``in development`` from ``CHANGES.rst``
+- remove ``(in development)`` from ``CHANGES.rst`` header
 
-Run the tests, run the linter, and build the docs:
+Run the tests, lint the code, and build the documentation:
 
 .. code:: bash
 
@@ -56,18 +62,16 @@ Commit to ``release`` branch and push to ``origin``:
 - Check Codecov ``release`` build `test coverage
   <https://app.codecov.io/gh/xflr6/graphviz/branch/release>`_
 
-Build the release:
+**Build** and check the release files:
 
 .. code:: bash
 
     $ python setup.py sdist bdist_wheel
 
-Check the release:
-
 - ``dist/graphviz-$MAJOR.$MINOR[.$BUGFIX].zip``
 - ``dist/graphviz-$MAJOR.$MINOR[.$BUGFIX]-py3-none-any.whl``
 
-If changes are needed (and go back to: **Cleanup**):
+If changes are needed (and go back to: **Cleanup** step):
 
 .. code:: bash
 
@@ -80,13 +84,13 @@ Switch to main branch and merge ``release``:
     $ git switch master
     $ git merge --ff-only release
 
-Create annotated release tag:
+**Tag** with annotated release version tag:
 
 .. code:: bash
 
     $ git tag -a -m "$MAJOR.$MINOR[.$BUGFIX] release"
 
-Bump post-release version to ``$MAJOR.$MINOR.[.$BUGFIX].dev0``:
+Bump **post-release version** to ``$MAJOR.$MINOR.[.$BUGFIX].dev0``:
 
 - ``docs/conf.py``
 - ``graphviz/__init__.py``
@@ -94,7 +98,7 @@ Bump post-release version to ``$MAJOR.$MINOR.[.$BUGFIX].dev0``:
 
 Document post-release:
 
-- edit ``CHANGES.rst`` (add ``Version $MAJOR.$MINOR[.$BUGFIX] (in development)``)
+- add new ``Version $MAJOR.$MINOR[.$BUGFIX] (in development)`` heading to ``CHANGES.rst``
 
 Commit version bump to main branch:
 
@@ -118,6 +122,14 @@ Push main branch and push all new tags:
 
     $ git push --tags
 
+Update `stable <https://github.com/xflr6/graphviz/tree/stable>`_ branch to the latest release:
+
+.. code:: bash
+
+    $ git switch stable
+    $ git merge --ff-only $MAJOR.$MINOR[.$BUGFIX]
+    $ git push
+
 
 Verify
 ------
@@ -130,6 +142,8 @@ Verify publication:
   <https://github.com/xflr6/graphviz/actions?query=branch%3Amaster>`_
 - Check Read the Docs `builds <https://readthedocs.org/projects/graphviz/builds/>`_
 - Check `latest release notes <https://graphviz.readthedocs.io/en/latest/changelog.html>`_
+- Check `stable release notes <https://graphviz.readthedocs.io/en/stable/changelog.html>`_
+- Check ``stable`` binder: https://mybinder.org/v2/gh/xflr6/graphviz/stable
 
 Install in default environment:
 
@@ -138,13 +152,8 @@ Install in default environment:
     $ pip install -U graphviz
     $ python -c "import graphviz; print((graphviz.__version__, graphviz.version()))"
 
-Update ``stable`` branch:
-
-- Set the ``stable`` branch to latest release.
-- Check `stable release notes <https://graphviz.readthedocs.io/en/stable/changelog.html>`_
-- Check binder: https://mybinder.org/v2/gh/xflr6/graphviz/stable
-
-Verify downstream:
+Downstream
+----------
 
 - Check downstream `conda-forge release <https://github.com/conda-forge/python-graphviz-feedstock>`_