Rewrite release instructions.

docs/src/developers_guide/release.rst

@@ -7,47 +7,112 @@ Releases
 
 A release of Iris is a `tag on the SciTools/Iris`_ Github repository.
 
-The summary below is of the main areas that constitute the release.  The final
-section details the :ref:`iris_development_releases_steps` to take.
+Below is :ref:`iris_development_releases_steps`, followed by some prose on the
+main areas that constitute the release.
+
+
+.. _iris_development_releases_steps:
+
+How to Create an Iris Release
+-----------------------------
+
+The step-by-step process is walked-through by a script at:
+``<Iris repo root>/tools/release_do_nothing.py``, and also available here:
+:doc:`release_do_nothing`.
 
 
 .. _release_manager:
 
 Release Manager
 ---------------
+
 A Release Manager will be nominated for each release of Iris. This role involves:
 
 * deciding which features and bug fixes should be included in the release
-* managing the project board for the release
+* managing the `GitHub Projects`_ board for the release
 * using :discussion:`GitHub Discussion releases category <categories/releases>`
   for documenting intent and capturing any
   discussion about the release
+* holding a developer retrospective post release, to look for potential
+  future improvements
 
 The Release Manager will make the release, ensuring that all the steps outlined
 on this page are completed.
 
 
+Versioning
+----------
+
+Iris' version numbers conform to `Semantic Versioning`_ (``MAJOR.MINOR.PATCH``)
+and `PEP 440`_.
+
+Iris uses `setuptools-scm`_ to automatically manage versioning based on Git
+tags. No manual versioning work is required within the files themselves.
+
+
+Release Candidate
+-----------------
+
+Prior to a release, a release candidate tag may be created, marked as a
+pre-release in GitHub, with a tag ending with :literal:`rc` followed by a
+number (0-based), e.g.,:
+
+    :literal:`v1.9.0rc0`
+
+If created, the pre-release shall be available for a minimum of 2 weeks
+prior to the release being cut.  However a 4 week period should be the goal
+to allow user groups to be notified of the existence of the pre-release and
+encouraged to test the functionality.
+
+A pre-release is expected for a major or minor release, but not for a
+patch release.
+
+If new features are required for a release after a release candidate has been
+cut, a new pre-release shall be issued first.
+
+Release candidates are made available as a conda package on the
+`conda-forge Anaconda channel`_ using the `rc_iris`_ label. This is achieved via
+the `conda-forge iris-feedstock`_ following `CFEP-05`_. For further information
+see the `conda-forge User Documentation`_.
+
+
+Patch Releases
+--------------
+
+Patch releases may be implemented to fix problems with previous major or minor
+releases. E.g. ``v1.9.1`` to fix a problem in ``v1.9.0``, both being part of
+the ``v1.9`` series.
+
+New features shall not be included in a patch release, these are for bug fixes.
+
+A patch release does not require a release candidate, but the rest of the
+release process is to be followed.
+
+
 Before Release
 --------------
 
 Deprecations
 ~~~~~~~~~~~~
 
-Ensure that any behaviour which has been deprecated for the correct number of
+Any behaviour which has been deprecated for the correct number of
 previous releases is now finally changed. More detail, including the correct
 number of releases, is in :ref:`iris_development_deprecations`.
 
 Standard Names
 ~~~~~~~~~~~~~~
 
-Update the file ``etc/cf-standard-name-table.xml`` to the latest CF standard names,
+The file ``etc/cf-standard-name-table.xml`` is updated to the latest CF standard names,
 from the `latest CF standard names`_.
 ( This is used during build to automatically generate the sourcefile
 ``lib/iris/std_names.py``. )
 
 
+The Release
+-----------
+
 Release Branch
---------------
+~~~~~~~~~~~~~~
 
 Once the features intended for the release are on ``main``, a release branch
 should be created, in the ``SciTools/iris`` repository.  This will have the name:
@@ -61,73 +126,93 @@ for example:
 This branch shall be used to finalise the release details in preparation for
 the release candidate.
 
+Changes for a **patch release** should target to the same release branch as the
+rest of the series. For example, a fix
+for a problem with the ``v1.9.0`` release will be merged into ``v1.9.x`` release
+branch, and then released with the tag ``v1.9.1``.
 
-Release Candidate
------------------
+Documentation
+~~~~~~~~~~~~~
 
-Prior to a release, a release candidate tag may be created, marked as a
-pre-release in GitHub, with a tag ending with :literal:`rc` followed by a
-number (0-based), e.g.,:
+The documentation should include a dedicated What's New file for this release
+series (e.g. ``v1.9.rst``), incorporating all of the What's New entries for the release.
+This content should be reviewed and adapted as required, including highlights
+at the top of the What's New document.
 
-    :literal:`v1.9.0rc0`
+What's New entries for **patch releases** should be added to the existing file
+for that release series (e.g. ``v1.9.1`` section in the ``v1.9.rst`` file).
 
-If created, the pre-release shall be available for a minimum of two weeks
-prior to the release being cut.  However a 4 week period should be the goal
-to allow user groups to be notified of the existence of the pre-release and
-encouraged to test the functionality.
+A template for What's New formatting can be found in the
+``docs/src/whatsnew/latest.rst.template`` file.
 
-A pre-release is expected for a major or minor release, but not for a
-point release.
 
-If new features are required for a release after a release candidate has been
-cut, a new pre-release shall be issued first.
+Tagging
+~~~~~~~
 
-Make the release candidate available as a conda package on the
-`conda-forge Anaconda channel`_ using the `rc_iris`_ label. To do this visit
-the `conda-forge iris-feedstock`_ and follow `CFEP-05`_. For further information
-see the `conda-forge User Documentation`_.
+Once all checks are complete, the release is published from the release
+branch - via the GitHub release functionality in the ``SciTools/iris``
+repository - which simultaneously creates a Git tag for the release.
 
 
-Documentation
--------------
+Post Release
+------------
 
-The documentation should include all of the ``whatsnew`` entries for the release.
-This content should be reviewed and adapted as required.
+PyPI
+~~~~
+Iris is available on PyPI as ``scitools-iris``.
 
-Steps to achieve this can be found in the :ref:`iris_development_releases_steps`.
+Iris' Continuous-Integration (CI) includes the automatic building and publishing of
+PyPI artifacts in a dedicated GitHub Action.
 
+Legacy manual instructions are appended to this page for reference purposes
+(:ref:`update_pypi`)
 
-The Release
------------
+conda-forge
+~~~~~~~~~~~
+
+Iris is available on conda-forge as ``iris``.
 
-The final steps of the release are to ensure that the release date and details
-are correct in the relevant ``whatsnew`` page within the documentation.
+This is managed via the the Iris conda recipe on the
+`conda-forge iris-feedstock`_, which is updated after the release is cut on
+GitHub, followed by automatic build and publish of the
+conda package on the `conda-forge Anaconda channel`_.
 
-There is no need to update the ``iris.__version__``, as this is managed
-automatically by `setuptools-scm`_.
+Announcement
+~~~~~~~~~~~~
 
-Once all checks are complete, the release is published on GitHub by
-creating a new tag in the ``SciTools/iris`` repository.
+Iris uses Twitter (`@scitools_iris`_) to announce new releases, as well as any
+internal message boards that are accessible (e.g. at the UK Met Office).
+Announcements usually include a highlighted feature to hook readers' attention.
 
+Citation
+~~~~~~~~
 
-Update conda-forge
-------------------
+``docs/src/userguide/citation.rst`` is updated to include
+the latest [non-release-candidate] version, date and `Zenodo DOI`_
+of the new release. Ideally this would be updated before the release, but
+the DOI for the new version is only available once the release has been
+created in GitHub.
+
+Merge Back
+~~~~~~~~~~
+
+After any release is published, **including patch releases**, the changes from the
+release branch should be merged back onto the ``SciTools/iris`` ``main`` branch.
 
-Once a release is cut on GitHub, update the Iris conda recipe on the
-`conda-forge iris-feedstock`_ for the release. This will build and publish the
-conda package on the `conda-forge Anaconda channel`_.
 
+Appendices
+----------
 
 .. _update_pypi:
 
-Update PyPI
------------
+Updating PyPI Manually
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. note::
 
   As part of our Continuous-Integration (CI), the building and publishing of
   PyPI artifacts is now automated by a dedicated GitHub Action.
-  
+
   The following instructions **no longer** require to be performed manually,
   but remain part of the documentation for reference purposes only.
 
@@ -145,7 +230,7 @@ Checkout the appropriate Iris ``<release>`` tag from the appropriate ``<repo>``.
 For example, to checkout tag ``v1.0`` from ``upstream``::
 
     > git fetch upstream --tags
-    > git checkout v1.0 
+    > git checkout v1.0
 
 Build the source distribution and wheel from the Iris root directory::
 
@@ -184,105 +269,6 @@ For further details on how to test Iris, see :ref:`developer_running_tests`.
     For further information on packaging and uploading a project to PyPI, please
     refer to `Generating Distribution Archives`_ and `Packaging Your Project`_.
 
-
-Merge Back
-----------
-
-After the release is published, the changes from the release branch should be merged
-back onto the ``SciTools/iris`` ``main`` branch.
-
-To achieve this, first cut a local branch from the latest ``main`` branch,
-and `git merge` the :literal:`.x` release branch into it. Ensure that the
-``docs/src/whatsnew/index.rst`` and ``docs/src/whatsnew/latest.rst`` are
-correct, before committing these changes and then proposing a pull-request
-on the ``main`` branch of ``SciTools/iris``.
-
-
-Point Releases
---------------
-
-Bug fixes may be implemented and targeted on the :literal:`.x` release branch.
-These should lead to a new point release, and another tag.  For example, a fix
-for a problem with the ``v1.9.0`` release will be merged into ``v1.9.x`` release
-branch, and then released by tagging ``v1.9.1``.
-
-New features shall not be included in a point release, these are for bug fixes.
-
-``whatsnew`` entries should be added to the existing 
-``docs/src/whatsnew/v1.9.rst`` file in a new ``v1.9.1`` section. A template for 
-this bugfix patches section can be found in the 
-``docs/src/whatsnew/latest.rst.template`` file.
-
-A point release does not require a release candidate, but the rest of the
-release process is to be followed, including the merge back of changes into
-``main``.
-
-
-.. _iris_development_releases_steps:
-
-Maintainer Steps
-----------------
-
-These steps assume a release for ``1.9.0`` is to be created.
-
-Release Steps
-~~~~~~~~~~~~~
-
-#. Update the ``whatsnew`` for the release:
-
-   * Use ``git`` to rename ``docs/src/whatsnew/latest.rst`` to the release
-     version file ``v1.9.rst``
-   * Use ``git`` to delete the ``docs/src/whatsnew/latest.rst.template`` file
-   * In ``v1.9.rst`` remove the ``[unreleased]`` caption from the page title.
-     Replace this with ``[release candidate]`` for the release candidate and
-     remove this for the actual release.
-     Note that, the Iris version and release date are updated automatically
-     when the documentation is built
-   * Review the file for correctness
-   * Work with the development team to populate the ``Release Highlights``
-     dropdown at the top of the file, which provides extra detail on notable
-     changes
-   * Use ``git`` to add and commit all changes, including removal of
-     ``latest.rst.template``.
-
-#. Update the ``whatsnew`` index ``docs/src/whatsnew/index.rst``
-
-   * Remove the reference to ``latest.rst``
-   * Add a reference to ``v1.9.rst`` to the top of the list
-
-#. Check your changes by building the documentation and reviewing
-#. Once all the above steps are complete, the release is cut, using
-   the :guilabel:`Draft a new release` button on the
-   `Iris release page <https://github.com/SciTools/iris/releases>`_
-   and targeting the release branch if it exists
-#. Create the release feature branch ``v1.9.x`` on `SciTools/iris`_ if it doesn't
-   already exist. For point/bugfix releases use the branch which already exists
-
-
-Post Release Steps
-~~~~~~~~~~~~~~~~~~
-
-#. Check the documentation has built on `Read The Docs`_.  The build is
-   triggered by any commit to ``main``.  Additionally check that the versions
-   available in the pop out menu in the bottom right corner include the new
-   release version.  If it is not present you will need to configure the
-   versions available in the **admin** dashboard in `Read The Docs`_.
-#. Review the `Active Versions`_ for the ``scitools-iris`` project on
-   `Read The Docs`_ to ensure that the appropriate versions are ``Active``
-   and/or ``Hidden``. To do this ``Edit`` the appropriate version e.g.,
-   see `Editing v3.0.0rc0`_ (must be logged into Read the Docs).
-#. Merge back to ``main``. This should be done after all releases, including
-   the release candidate, and also after major changes to the release branch.
-#. On main, make a new ``latest.rst`` from ``latest.rst.template`` and update
-   the include statement and the toctree in ``index.rst`` to point at the new
-   ``latest.rst``.
-#. Consider updating ``docs/src/userguide/citation.rst`` on ``main`` to include 
-   the version number, date and `Zenodo DOI <https://doi.org/10.5281/zenodo.595182>`_ 
-   of the new release. Ideally this would be updated before the release, but 
-   the DOI for the new version is only available once the release has been 
-   created in GitHub.
-
-
 .. _SciTools/iris: https://github.com/SciTools/iris
 .. _tag on the SciTools/Iris: https://github.com/SciTools/iris/releases
 .. _conda-forge Anaconda channel: https://anaconda.org/conda-forge/iris
@@ -294,5 +280,10 @@ Post Release Steps
 .. _rc_iris: https://anaconda.org/conda-forge/iris/labels
 .. _Generating Distribution Archives: https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives
 .. _Packaging Your Project: https://packaging.python.org/guides/distributing-packages-using-setuptools/#packaging-your-project
-.. _latest CF standard names: http://cfconventions.org/standard-names.html
+.. _latest CF standard names: http://cfconventions.org/Data/cf-standard-names/current/src/cf-standard-name-table.xml
 .. _setuptools-scm: https://github.com/pypa/setuptools_scm
+.. _Semantic Versioning: https://semver.org/
+.. _PEP 440: https://peps.python.org/pep-0440/
+.. _@scitools_iris: https://twitter.com/scitools_iris
+.. _GitHub Projects: https://github.com/SciTools/iris/projects
+.. _Zenodo DOI: https://doi.org/10.5281/zenodo.595182

docs/src/developers_guide/release_do_nothing.rst

@@ -0,0 +1,12 @@
+:orphan:
+
+Release Do-Nothing Script
+-------------------------
+
+Rendered from the original ``<Iris repo root>/tools/release_do_nothing.py``.
+
+`Read more about do-nothing scripts
+<https://blog.danslimmon.com/2019/07/15/do-nothing-scripting-the-key-to-gradual-automation/>`_
+
+.. literalinclude:: ../../../tools/release_do_nothing.py
+   :language: python