From c797fc88a0da727badf523136599bed7215bd716 Mon Sep 17 00:00:00 2001 From: Martin Yeo <40734014+trexfeathers@users.noreply.github.com> Date: Mon, 12 Oct 2020 09:22:09 +0100 Subject: [PATCH] Release Docs Improvements (#3895) * Minor phrasing change in 'Release candidate'. * Before release deprecations. * Whatsnew highlights section. --- docs/iris/src/developers_guide/release.rst | 37 +++++++++++++++------- 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/iris/src/developers_guide/release.rst b/docs/iris/src/developers_guide/release.rst index d71f149186..2ec787a780 100644 --- a/docs/iris/src/developers_guide/release.rst +++ b/docs/iris/src/developers_guide/release.rst @@ -3,17 +3,28 @@ Releases ======== -A release of Iris is a `tag on the SciTools/Iris`_ +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. +Before release +-------------- + +Deprecations +~~~~~~~~~~~~ + +Ensure that 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`. + + Release branch -------------- -Once the features intended for the release are on master, a release branch +Once the features intended for the release are on master, a release branch should be created, in the SciTools/Iris repository. This will have the name: :literal:`v{major release number}.{minor release number}.x` @@ -35,12 +46,12 @@ number, e.g.: :literal:`v1.9.0rc1` -If created, the pre-release shall be available for a minimum of two weeks +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 pre-release is expected for a minor release, but will not for a +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 @@ -59,7 +70,7 @@ Steps to achieve this can be found in the :ref:`iris_development_releases_steps` The release ----------- -The final steps are to change the version string in the source of +The final steps are to change the version string in the source of :literal:`Iris.__init__.py` and include the release date in the relevant what's new page within the documentation. @@ -72,7 +83,7 @@ Conda recipe Once a release is cut, the `Iris feedstock`_ for the conda recipe must be updated to build the latest release of Iris and push this artefact to -`conda forge`_. +`conda forge`_. .. _Iris feedstock: https://github.com/conda-forge/iris-feedstock/tree/master/recipe .. _conda forge: https://anaconda.org/conda-forge/iris @@ -102,7 +113,7 @@ New features shall not be included in a point release, these are for bug fixes. 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 -:literal:`master`. +:literal:`master`. .. _iris_development_releases_steps: @@ -118,7 +129,7 @@ Release steps #. Create the branch ``1.9.x`` on the main repo, not in a forked repo, for the release candidate or release. The only exception is for a point/bugfix release as it should already exist -#. Update the what's new for the release: +#. Update the what's new for the release: * Copy ``docs/iris/src/whatsnew/latest.rst`` to a file named ``v1.9.rst`` @@ -128,6 +139,8 @@ Release steps the date and version in the format of ``v1.9 (DD MMM YYYY)``. For example ``v1.9 (03 Aug 2020)`` * Review the file for correctness + * Work with the development team to create a 'highlights' section at the + top of the file, providing extra detail on notable changes * Add ``v1.9.rst`` to git and commit all changes, including removal of ``latest.rst`` @@ -138,7 +151,7 @@ Release steps #. Update the ``Iris.__init__.py`` version string, to ``1.9.0`` #. Check your changes by building the documentation and viewing the changes -#. Once all the above steps are complete, the release is cut, using +#. Once all the above steps are complete, the release is cut, using the :guilabel:`Draft a new release` button on the `Iris release page `_ @@ -146,16 +159,16 @@ Release steps Post release steps ~~~~~~~~~~~~~~~~~~ -#. Check the documentation has built on `Read The Docs`_. The build is +#. Check the documentation has built on `Read The Docs`_. The build is triggered by any commit to master. Additionally check that the versions available in the pop out menu in the bottom left 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 -#. Copy ``docs/iris/src/whatsnew/latest.rst.template`` to +#. Copy ``docs/iris/src/whatsnew/latest.rst.template`` to ``docs/iris/src/whatsnew/latest.rst``. This will reset the file with the ``unreleased`` heading and placeholders for the what's new headings -#. Add back in the reference to ``latest.rst`` to the what's new index +#. Add back in the reference to ``latest.rst`` to the what's new index ``docs/iris/src/whatsnew/index.rst`` #. Update ``Iris.__init__.py`` version string to show as ``1.10.dev0`` #. Merge back to master