******************
Release Procedures
******************
The current release procedure for Astropy involves a combination of an
automated release script and some manual steps. Future versions will automate
more of the process, if not all.
There are several different procedures below, depending on the situation:
* :ref:`release-procedure`
- :ref:`release-procedure-beta-rc`
* :ref:`release-procedure-new-major`
* :ref:`release-procedure-bug-fix`
- :ref:`release-procedure-bug-fix-backport`
- :ref:`release-procedure-bug-fix-direct`
- :ref:`release-procedure-bug-fix-release`
For a signed release, see :ref:`key-signing-info` for relevant setup
instructions.
.. _release-procedure:
Standard Release Procedure
==========================
This is the standard release procedure for releasing Astropy (or affiliated
packages that use the full bugfix/maintenance branch approach.)
#. Create a github milestone for the next bugfix version, move any remaining
issues from the version you are about to release, and close the milestone.
When releasing a major release, close the last milestone on the previous
maintenance branch, too.
.. note::
Creation of new milestone can be done as early as when you ping
maintainers about their relevant pull requests, so that the maintainers
have the option to re-milestone their work.
#. If there are any issues in the Github issue tracker that are labeled
``affects-dev`` but are issues that apply to this release, update them to
``affects-release``. Similarly, if any issues remain open for this release,
re-assign them to the next relevant milestone.
#. (Only for major versions) Make sure to update the "What's new"
section with the stats on the number of issues, PRs, and contributors. For
the first two, the `astropy-procedures repository`_ script ``gh_issuereport.py``
can provide the numbers since the last major release. For the final one, you
will likely need to update the Astropy ``.mailmap`` file, as there are often
contributors who are not careful about using the same e-mail address for
every commit. The easiest way to do this is to run the command
``git shortlog -n -s -e`` to see the list of all contributors and their email
addresses. Look for any misnamed entries or duplicates, and add them to the
``.mailmap`` file (matched to the appropriate canonical name/email address.)
Once you have finished this, you can count the number of lines in
``git shortlog -s`` to get the final contributor count.
#. Also be sure to update the ``docs/credits.rst`` file to include any new
contributors. This can come from the above step, or the ``author_lists.py``
script in the `astropy-procedures repository`_ mostly automates this. (This
step is only required on major releases, but can be done for bugfix releases
as time allows.)
#. (astropy specific) Ensure the built-in IERS earth rotation parameter and
leap second tables are up to date by changing directory to
``astropy/utils/iers/data`` and executing ``update_builtin_iers.sh``.
Check the result with ``git diff`` (do not be surprised to find many lines
in the ``eopc04_IAU2000.62-now`` file change; those data are reanalyzed
periodically) and committing.
#. To build the source distribution in an isolated environment and make sure you
have all the dependencies required for it, install the `pep517
`_ package::
$ pip install pep517 --upgrade
#. Ensure you have a GPG key pair available for when git needs to sign the
tag you create for the release. See :ref:`key-signing-info` for more on
this.
#. Obtain a *clean* version of the `astropy core repository`_. That is, one
where you don't have any intermediate build files. Either use a fresh
``git clone`` or do ``git clean -dfx``.
#. Be sure you're on the branch appropriate for the version you're about to
release. For example, if releasing version 1.2.2 make sure to::
$ git checkout v1.2.x
#. Make sure that the continuous integration services (e.g., Travis or CircleCI) are passing
for the `astropy core repository`_ branch you are going to release. You may
also want to locally run the tests (with remote data on to ensure all of the
tests actually run), using tox to do a thorough test in an isolated environment::
$ pip install tox --upgrade
$ TEST_READ_HUGE_FILE=1 tox -e test-alldeps -- --remote-data=any
#. Edit the ``CHANGES.rst`` file by changing the date for the version you are
about to release from "unreleased" to today's date. Also be sure to remove
any sections of the changelog for that version that have no entries.
For releases that come after release candidates (:ref:`release-procedure-beta-rc`),
the title of the changelog section should be replaced too, thus getting rid
of any mention of the release candidate.
Then add and commit those changes with::