Improvements to the release guide (#3070)

Co-authored-by: Davis Bennett <[email protected]>

Author: dstansby

docs/developers/contributing.rst

@@ -251,14 +251,11 @@ See the `towncrier`_ docs for more.
 
 .. _towncrier: https://towncrier.readthedocs.io/en/stable/tutorial.html
 
-Development best practices, policies and procedures
----------------------------------------------------
-
 The following information is mainly for core developers, but may also be of interest to
 contributors.
 
 Merging pull requests
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Pull requests submitted by an external contributor should be reviewed and approved by at least
 one core developer before being merged. Ideally, pull requests submitted by a core developer
@@ -268,10 +265,10 @@ Pull requests should not be merged until all CI checks have passed (GitHub Actio
 Codecov) against code that has had the latest main merged in.
 
 Compatibility and versioning policies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 Versioning
-""""""""""
+~~~~~~~~~~
 Versions of this library are identified by a triplet of integers with the form
 ``<major>.<minor>.<patch>``, for example ``3.0.4``. A release of ``zarr-python`` is associated with a new
 version identifier. That new identifier is generated by incrementing exactly one of the components of
@@ -323,7 +320,7 @@ backwards-compatible changes wherever possible. When a backwards-incompatible ch
 users should be notified well in advance, e.g. via informative deprecation warnings.
 
 Data format compatibility
-^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""
 
 The Zarr library is an implementation of a file format standard defined externally --
 see the `Zarr specifications website <https://zarr-specs.readthedocs.io>`_ for the list of
@@ -340,36 +337,28 @@ breaking changes may be more frequent than usual.
 
 
 Release procedure
-~~~~~~~~~~~~~~~~~
-
-.. note::
-
-   Most of the release process is now handled by GitHub workflow which should
-   automatically push a release to PyPI if a tag is pushed.
+-----------------
 
 Pre-release
-"""""""""""
+~~~~~~~~~~~
 1. Make sure that all pull requests which will be included in the release
-   have been properly documented as changelog files in :file:`changes`.
-2. Run ``towncrier build --version x.y.z`` to create the changelog.
+   have been properly documented as changelog files in the :file:`changes/` directory.
+2. Run ``towncrier build --version x.y.z`` to create the changelog, and commit the result
+   to the main branch.
 
 Releasing
-"""""""""
-To make a new release, go to
-https://github.com/zarr-developers/zarr-python/releases and
-click "Draft a new release". Choose a version number prefixed
-with a `v` (e.g. `v0.0.0`). For pre-releases, include the
-appropriate suffix (e.g. `v0.0.0a1` or `v0.0.0rc2`).
-
-
-Set the description of the release to::
+~~~~~~~~~
+1. Go to https://github.com/zarr-developers/zarr-python/releases
+2. Click "Draft a new release".
+3. Choose a version number prefixed with a `v` (e.g. `v0.0.0`).
+   For pre-releases, include the appropriate suffix (e.g. `v0.0.0a1` or `v0.0.0rc2`).
+4. Set the description of the release to::
 
     See release notes https://zarr.readthedocs.io/en/stable/release-notes.html#release-0-0-0
 
-replacing the correct version numbers. For pre-release versions,
-the URL should omit the pre-release suffix, e.g. "a1" or "rc1".
-
-Click on "Generate release notes" to auto-file the description.
+   replacing the correct version numbers. For pre-release versions,
+   the URL should omit the pre-release suffix, e.g. "a1" or "rc1".
+5. Click on "Generate release notes" to auto-fill the description.
 
 After creating the release, the documentation will be built on
 https://readthedocs.io. Full releases will be available under
@@ -378,9 +367,8 @@ pre-releases will be available under
 `/latest <https://zarr.readthedocs.io/en/latest>`_.
 
 Post-release
-""""""""""""
+~~~~~~~~~~~~
 
 - Review and merge the pull request on the
   `conda-forge feedstock <https://github.com/conda-forge/zarr-feedstock>`_ that will be
   automatically generated.
-- Create a new "Unreleased" section in the release notes