Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update release process #4010

Merged
merged 1 commit into from
Feb 15, 2021
Merged

update release process #4010

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 55 additions & 42 deletions docs/src/developers_guide/release.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@
Releases
========

A release of Iris is a `tag on the SciTools/Iris`_
Github repository.
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.
Expand All @@ -24,8 +23,8 @@ number of releases, is in :ref:`iris_development_deprecations`.
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:
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`

Expand All @@ -41,10 +40,10 @@ 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, e.g.:
pre-release in GitHub, with a tag ending with :literal:`rc` followed by a
number (0-based), e.g.,:

:literal:`v1.9.0rc1`
:literal:`v1.9.0rc0`

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
Expand All @@ -57,11 +56,16 @@ 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.

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`_.


Documentation
-------------

The documentation should include all of the what's new entries for the release.
The documentation should include all of the ``whatsnew`` entries for the release.
This content should be reviewed and adapted as required.

Steps to achieve this can be found in the :ref:`iris_development_releases_steps`.
Expand All @@ -70,81 +74,79 @@ 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
:literal:`Iris.__init__.py` and include the release date in the relevant what's
new page within the documentation.
The final steps of the release are to change the version string ``__version__``
in the source of :literal:`iris.__init__.py` and ensure the release date and details
are correct in the relevant ``whatsnew`` page within the documentation.

Once all checks are complete, the release is cut by the creation of a new tag
in the SciTools Iris repository.
in the ``SciTools/iris`` repository.


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`_.
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`_.

.. _Iris feedstock: https://github.com/conda-forge/iris-feedstock/tree/master/recipe
.. _conda forge: https://anaconda.org/conda-forge/iris

Merge Back
----------

After the release is cut, the changes shall be merged back onto the
Scitools/iris master branch.
After the release is cut, the changes from the release branch should be merged
back onto the ``SciTools/iris`` ``master`` branch.

To achieve this, first cut a local branch from the release branch,
:literal:`{release}.x`. Next add a commit changing the release string to match
the release string on scitools/master. This branch can now be proposed as a
pull request to master. This work flow ensures that the commit identifiers are
consistent between the :literal:`.x` branch and :literal:`master`.
To achieve this, first cut a local branch from the latest ``master`` branch,
and `git merge` the :literal:`.x` release branch into it. Ensure that the
``iris.__version__``, ``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 ``master`` branch of ``SciTools/iris``.


Point Releases
--------------

Bug fixes may be implemented and targeted as the :literal:`.x` branch. These
should lead to a new point release, another tag. For example, a fix for a
problem with 1.9.0 will be merged into 1.9.x, and then released by tagging
1.9.1.
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.

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`.
``master``.


.. _iris_development_releases_steps:

Maintainer Steps
----------------

These steps assume a release for ``v1.9`` is to be created.
These steps assume a release for ``1.9.0`` is to be created.

Release Steps
~~~~~~~~~~~~~

#. Create the release feature branch ``1.9.x`` on `SciTools/iris`_.
#. Create the release feature branch ``v1.9.x`` on `SciTools/iris`_.
The only exception is for a point/bugfix release, as it should already exist
#. Update the ``iris.__init__.py`` version string e.g., to ``1.9.0``
#. Update the what's new for the release:
#. Update the ``whatsnew`` for the release:

* Use git to rename ``docs/src/whatsnew/latest.rst`` to 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
* Use ``git`` to delete the ``docs/src/whatsnew/latest.rst.template`` file
* In ``v1.9.rst`` remove the ``[unreleased]`` caption from the page title.
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
* Use ``git`` to add and commit all changes, including removal of
``latest.rst.template``

#. Update the what's new index ``docs/src/whatsnew/index.rst``
#. 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
Expand All @@ -159,20 +161,31 @@ Post Release Steps
~~~~~~~~~~~~~~~~~~

#. Check the documentation has built on `Read The Docs`_. The build is
triggered by any commit to master. Additionally check that the versions
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
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`_.
#. Copy ``docs/src/whatsnew/latest.rst.template`` to
``docs/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
the file with the ``unreleased`` heading and placeholders for the
``whatsnew`` headings
#. Add back in the reference to ``latest.rst`` to the ``whatsnew`` index
``docs/src/whatsnew/index.rst``
#. Update ``iris.__init__.py`` version string to show as ``1.10.dev0``
#. Merge back to master
#. Merge back to ``master``


.. _Read The Docs: https://readthedocs.org/projects/scitools-iris/builds/
.. _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
.. _conda-forge iris-feedstock: https://github.com/conda-forge/iris-feedstock
.. _CFEP-05: https://github.com/conda-forge/cfep/blob/master/cfep-05.md
.. _conda-forge User Documentation: https://conda-forge.org/docs/user/00_intro.html
.. _Active Versions: https://readthedocs.org/projects/scitools-iris/versions/
.. _Editing v3.0.0rc0: https://readthedocs.org/dashboard/scitools-iris/version/v3.0.0rc0/
.. _rc_iris: https://anaconda.org/conda-forge/iris/labels