<commit_before>******************
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.


.. _release-procedure:

Release Procedure
=================

This is the standard release procedure for releasing Astropy (or affiliated
packages that use the full bugfix/maintenance branch approach.)

#. (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-tools 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 mis-named 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 could 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-tools repository`_ mostly automates this.  (This
   step is only required on major releases, but can be done for bugfix releases
   as time allows.)

#. (Optional) You may want to set up a clean environment to build the release.
   For more on setting up virtual environments, see :ref:`virtual_envs`, but
   for the sake of example we will assume you're using `Anaconda`_. This is not
   necessary if you know your normal python environment has what you need, but
   you might want to do something like this for safety's sake::

      $ conda create -n astropy_release_build_v<version> astropy
      $ source activate astropy_release_build_v<version>
      $ conda uninstall astropy  # still keeps the dependencies
      $ pip install -r pip-requirements-dev  # any that might be left over

#. Before doing a release of Astropy, you may need to do a release of
   astropy-helpers.  This is not always necessary, as there are not always any
   significant changes in the helpers.  See :ref:`helpers-release-info` for more
   on this.


#. Make sure that the continuous integration services (e.g., Travis) are passing
   for the `astropy core repository`_ branch you're going to release.  You may
   also want to locally run the tests (with remote data on to ensure all the
   tests actually run), and make sure the description in ``setup.py`` is ReST
   compliant::

      $ python setup.py test --remote-data=any
      $ python setup.py check --restructuredtext

#. 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``. If you choose to clean the working tree,
   don't forget to clean the ``astropy_helpers`` submodule, too.

#. 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

#. 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.  Then
   add and commit those changes with::

      <use your favorite editor on CHANGES.rst>
      $ git add CHANGES.rst
      $ git commit -m "Finalizing changelog for v<version>"




#. Edit the ``setup.py`` file by removing the ``".dev"`` at the end of the
   ``VERSION`` string, then add and commit that change as the final step prior
   to release::

      <use your favorite editor on setup.py>
      $ git add setup.py
      $ git commit -m "Preparing release v<version>"

#. Tag the commit with ``v<version>``, being certain to sign the tag with the
   ``-s`` option::

      $ git tag -s v<version> -m "Tagging v<version>"

#. Edit the ``VERSION`` in ``setup.py`` to be the next version number, but with
   a ``.dev`` suffix at the end (E.g., ``1.2.3.dev``).  Then add and commit::

      <use your favorite editor on setup.py>
      $ git add setup.py
      $ git commit -m "Back to development: v<next_version>.dev"

#. Also update the ``CHANGES.rst`` file with a new section for the next version.
   You will likely want to use the ``add_to_changelog.py`` script in the
   `astropy-tools repository`_ for this.  Then add and commit::

      <use your favorite editor on CHANGES.rst>
      $ git add CHANGES.rst
      $ git commit -m "Add v<next_version> to the changelog"

#. Now go back and check out the tag of the released version with
   ``git checkout v<version>``.  For example::

      $ git checkout v1.2.2

   Don't forget to remove any non-committed files both from the main working tree
   and ``astropy_helpers`` submodules with::

      $ git clean -dfx
      $ cd astropy_helpers; git clean -dfx; cd ..

#. Make sure the source distribution doesn't inherit limited permissions
   following your default umask::

     $ umask 0022
     $ chmod -R a+Xr .

#. Create the source distribution by doing::

         $ python setup.py build sdist

   .. note::

       In the future, the ``build`` command may run automatically as a
       prerequisite for ``sdist``.  But for now, make sure to run it
       whenever running ``sdist`` to ensure that all Cython sources and
       other generated files are built.

#. Run the tests in an environment that mocks up a "typical user" scenario.
   This is not strictly necessary because you ran the tests above, but
   it can sometimes be useful to catch subtle bugs that might come from you
   using a customized developer environment.  For more on setting up virtual
   environments, see :ref:`virtual_envs`, but for the sake of example we will
   assume you're using `Anaconda`_. Do::

      $ conda create -n astropy_release_test_v<version> numpy
      $ source activate astropy_release_test_v<version>
      $ pip install dist/astropy-<version>.tar.gz
      $ python -c 'import astropy; astropy.test(remote_data=True)'
      $ source deactivate

#. Build and test the Astropy wheels.  See the `wheel builder README
   <https://github.com/MacPython/astropy-wheels>`_ for instructions.  In
   summary, clone the wheel-building repo, edit the ``.travis.yml`` and
   ``appveyor.yml`` text files with the branch or commit for the release,
   commit and then push back up to github.  This will trigger a wheel build
   and test on OSX, Linux and Windows. Check the build has passed on on the
   Travis-CI interface at https://travis-ci.org/MacPython/astropy-wheels.
   You'll need commit privileges to the ``astropy-wheels`` repo; ask <NAME>
   or on the mailing list if you do not have them.

#. If the tests do *not* pass, you'll have to fix whatever the problem is.
   First you'll need to back out the release procedure by dropping the commits
   you made for release and removing the tag you created::

      $ git reset --hard HEAD^^^^ # you could also use the SHA hash of the commit before your first changelog edit
      $ git tag -d v<version>

#. Once the tests are all passing, it's time to actually proceed with the
   release! This has two steps:

   * build and upload the Astropy wheels;
   * make and upload the Astropy source release.
   

#. For the wheel build / upload, follow the `wheel builder README`_
   instructions again.  Edit the ``.travis.yml`` and ``appveyor.yml`` files
   to give the release tag to build.  Check the build has passed on on the
   Travis-CI interface at https://travis-ci.org/MacPython/astropy-wheels.  Now
   follow the instructions in the page above to download the built wheels to a
   local machine and upload to PyPI. If you use the ``wheel_download.py`` script,
   make sure you loop through all the available OS to get all the wheels.

#. Now the wheels are built and uploaded, you can upload the source release.
   For safety's sake, you may want to clean the repo yet again to make sure
   you didn't leave anything from the previous step::

      $ git clean -dfx
      $ cd astropy_helpers; git clean -dfx; cd ..

#. Upload the source distribution to PyPI; this is preceded by re-running
   the sdist command, which makes sure the source code is packaged up and ready
   to be uploaded. You also need to GPG sign the release, before using twine to
   upload it to PyPI. (You may need to install `twine`_ if you haven't used it yet)::

      $ python setup.py build sdist
      $ gpg --detach-sign -a dist/astropy-<version>.tar.gz
      $ twine upload dist/astropy-<version>*
      
#. Go to https://pypi.python.org/pypi?:action=pkg_edit&name=astropy
   and ensure that only the most recent releases in each actively maintained
   release line are *not* marked hidden.  For example, if v1.2.2 was
   just released, v1.2.1 should be hidden.  This is so that users only find
   the latest bugfix releases.

   Do not enabled "Auto-hide old releases" as that may hide bugfix releases
   from older release lines that we may still want to make available.

#. Push up these changes and the tag to the `astropy core repository`_::

      $ git push upstream v<version branch>.x
      $ git push upstream v<version branch>

   .. note::

      You may need to replace ``upstream`` here with ``astropy`` or
      whatever remote name you use for the `astropy core repository`_.
      Also, it might be tempting to use the ``--tags`` argument to ``git push``,
      but this should *not* be done, as it might push up some unintended tags.

#. If this is a release of the current release (i.e., not an LTS supported along
   side a more recent version), update the "stable" branch to point to the new
   release::

      $ git checkout stable
      $ git reset --hard v<version>
      $ git push upstream stable --force

#. Update Readthedocs so that it builds docs for the version you just released.
   You'll find this in the "admin" tab, with checkboxes next to each github tag.
   Also verify that the ``stable`` Readthedocs version builds correctly for
   the new version (it should trigger automatically once you've done the
   previous step).

#. When releasing a patch release, also set the previous RTD version in the
   release history to "protected".  For example when releasing v1.1.2, set
   v1.1.1 to "protected".  This prevents the previous releases from
   cluttering the list of versions that users see in the version dropdown
   (the previous versions are still accessible by their URL though).

#. Update the Astropy web site by editing the ``index.html`` page at
   https://github.com/astropy/astropy.github.com by changing the "current
   version" link and/or updating the list of older versions if this is an LTS
   bugfix or a new major version.  You may also need to update the contributor
   list on the web site if you updated the ``docs/credits.rst`` at the outset.

#. In the astropy *master* branch (not just the maintenance branch), be sure to
   update the ``CHANGES.rst`` to reflect the date of the release you just
   performed and to include the new section of the changelog.  Often the easiest
   way to do this is to use ``git cherry-pick`` the changelog commit just before
   the release commit from above. If you aren't sure how to do this, you might
   be better off just copying-and-pasting the relevant parts of the maintenance
   branch's ``CHANGES.rst`` into master.

#. 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.

#. Create a github milestone for the next bugfix version, move any remaining
   issues from the version you just released, and close the milestone. When
   releasing a major release, close the last milestone on the previous
   maintenance branch, too.

#. Notify the Conda Distribution Maintainer and the Continuous Integration
   maintainer about the new release.  Typically, you should wait to make sure
   ``conda-forge`` and possible ``conda`` works before sending out the public
   announcement (so that users that want to try out the new version can do
   so on conda).

#. Update the ``LATEST_ASTROPY_STABLE`` or ``ASTROPY_LTS_VERSION`` variables
   in the ``ci-helpers`` repository once the ``conda`` packages became
   available.


Modifications for a beta/release candidate release
--------------------------------------------------

   For major releases we do beta and/or release candidates to have a chance to
   catch significant bugs before the true release. If the release you are
   performing is this kind of pre-release, some of the above steps need to be
   modified.

   The primary modifications to the release procedure are:

   * When entering the new version number, instead of just removing the
     ``.dev``, enter "1.2b1" or "1.2rc1".  It is critical that you follow this
     numbering scheme (``x.yb#`` or ``x.y.zrc#``), as it will ensure the release
     is ordered "before" the main release by various automated tools, and also
     tells PyPI that this is a "pre-release".
   * Do *not* do the step of adding ``.dev`` in the "back to development" stage.
     If an RC goes well, there's no need for a "dev" stage, as the same version
     will be released with only minor doc updates, and strings like "x.yrcz.dev"
     confuse some version number parsing tools.
   * Do not do step #26 or later, as those are tasks for an actual release.


Performing a Feature Freeze/Branching new Major Versions
========================================================

As outlined in
`APE2 <https://github.com/astropy/astropy-APEs/blob/master/APE2.rst>`_, astropy
releases occur at regular intervals, but feature freezes occur well before the
actual release.  Feature freezes are also the time when the master branch's
development separates from the new major version's maintenance branch.  This
allows new development for the next major version to continue while the
soon-to-be-released version can focus on bug fixes and documentation updates.

The procedure for this is straightforward:

#. Make sure you're on master, and updated to the latest version from github::

      $ git fetch upstream
      $ git checkout upstream/master

#. Create a new branch from master at the point you want the feature freeze to
   occur::

      $ git branch v<version>.x

#. Update the ``VERSION`` in ``setup.py`` to reflect the new major version. For
   example, if you are about to issue a feature freeze for version ``1.2``, you
   will want to set the new version to ``'1.3.dev'``. Then add and commit that::

      <use your favorite editor on setup.py>
      $ git add setup.py
      $ git commit -m "Next major version: <next_version>"

#. Update the ``CHANGES.rst`` file with a new section at the very top for the
   next major version.  You will likely want to use the ``add_to_changelog.py``
   script in the `astropy-tools repository`_ for this. Then add and commit those
   changes::

      <use your favorite editor on CHANGES.rst>
      $ git add CHANGES.rst
      $ git commit -m "Add <next_version> to changelog"

#. Also update the "what's new" section of the docs to include a section for the
   next major version.  E.g.::

      $ cp docs/whatsnew/<current_version>.rst docs/whatsnew/<next_version>.rst

   You'll then need to edit ``docs/whatsnew/<next_version>.rst``, removing all
   the content but leaving the basic structure.  You may also need  to
   replace the "by the numbers" numbers with "xxx" as a reminder to update them
   before the next release. Then add the new version to the top of
   ``docs/whatsnew/index.rst``, update the reference in ``docs/index.rst`` to
   point to the that version, and commit these changes ::

      $ git add docs/whatsnew/<next_version>.rst
      $ git add docs/whatsnew/index.rst
      $ git add docs/index.rst
      $ git commit -m "Added <next_version> whats new section"

#. Push all of these changes up to github::

      $ git push upstream v<version>.x:v<version>.x
      $ git push upstream HEAD:master

   .. note::

      You may need to replace ``upstream`` here with ``astropy`` or
      whatever remote name you use for the `astropy core repository`_.

#. On the github issue tracker, add a new milestone for the next major version.

#. Repeat the above steps for the astropy-helpers, using the same version series.

Maintaining Bug Fix Releases
============================

Astropy releases, as recommended for most Python projects, follows a<commit_msg>change branching instructions to use master instead of HEAD local branch<commit_after>******************
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.


.. _release-procedure:

Release Procedure
=================

This is the standard release procedure for releasing Astropy (or affiliated
packages that use the full bugfix/maintenance branch approach.)

#. (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-tools 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 mis-named 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 could 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-tools repository`_ mostly automates this.  (This
   step is only required on major releases, but can be done for bugfix releases
   as time allows.)

#. (Optional) You may want to set up a clean environment to build the release.
   For more on setting up virtual environments, see :ref:`virtual_envs`, but
   for the sake of example we will assume you're using `Anaconda`_. This is not
   necessary if you know your normal python environment has what you need, but
   you might want to do something like this for safety's sake::

      $ conda create -n astropy_release_build_v<version> astropy
      $ source activate astropy_release_build_v<version>
      $ conda uninstall astropy  # still keeps the dependencies
      $ pip install -r pip-requirements-dev  # any that might be left over

#. Before doing a release of Astropy, you may need to do a release of
   astropy-helpers.  This is not always necessary, as there are not always any
   significant changes in the helpers.  See :ref:`helpers-release-info` for more
   on this.


#. Make sure that the continuous integration services (e.g., Travis) are passing
   for the `astropy core repository`_ branch you're going to release.  You may
   also want to locally run the tests (with remote data on to ensure all the
   tests actually run), and make sure the description in ``setup.py`` is ReST
   compliant::

      $ python setup.py test --remote-data=any
      $ python setup.py check --restructuredtext

#. 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``. If you choose to clean the working tree,
   don't forget to clean the ``astropy_helpers`` submodule, too.

#. 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

#. 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.  Then
   add and commit those changes with::

      <use your favorite editor on CHANGES.rst>
      $ git add CHANGES.rst
      $ git commit -m "Finalizing changelog for v<version>"




#. Edit the ``setup.py`` file by removing the ``".dev"`` at the end of the
   ``VERSION`` string, then add and commit that change as the final step prior
   to release::

      <use your favorite editor on setup.py>
      $ git add setup.py
      $ git commit -m "Preparing release v<version>"

#. Tag the commit with ``v<version>``, being certain to sign the tag with the
   ``-s`` option::

      $ git tag -s v<version> -m "Tagging v<version>"

#. Edit the ``VERSION`` in ``setup.py`` to be the next version number, but with
   a ``.dev`` suffix at the end (E.g., ``1.2.3.dev``).  Then add and commit::

      <use your favorite editor on setup.py>
      $ git add setup.py
      $ git commit -m "Back to development: v<next_version>.dev"

#. Also update the ``CHANGES.rst`` file with a new section for the next version.
   You will likely want to use the ``add_to_changelog.py`` script in the
   `astropy-tools repository`_ for this.  Then add and commit::

      <use your favorite editor on CHANGES.rst>
      $ git add CHANGES.rst
      $ git commit -m "Add v<next_version> to the changelog"

#. Now go back and check out the tag of the released version with
   ``git checkout v<version>``.  For example::

      $ git checkout v1.2.2

   Don't forget to remove any non-committed files both from the main working tree
   and ``astropy_helpers`` submodules with::

      $ git clean -dfx
      $ cd astropy_helpers; git clean -dfx; cd ..

#. Make sure the source distribution doesn't inherit limited permissions
   following your default umask::

     $ umask 0022
     $ chmod -R a+Xr .

#. Create the source distribution by doing::

         $ python setup.py build sdist

   .. note::

       In the future, the ``build`` command may run automatically as a
       prerequisite for ``sdist``.  But for now, make sure to run it
       whenever running ``sdist`` to ensure that all Cython sources and
       other generated files are built.

#. Run the tests in an environment that mocks up a "typical user" scenario.
   This is not strictly necessary because you ran the tests above, but
   it can sometimes be useful to catch subtle bugs that might come from you
   using a customized developer environment.  For more on setting up virtual
   environments, see :ref:`virtual_envs`, but for the sake of example we will
   assume you're using `Anaconda`_. Do::

      $ conda create -n astropy_release_test_v<version> numpy
      $ source activate astropy_release_test_v<version>
      $ pip install dist/astropy-<version>.tar.gz
      $ python -c 'import astropy; astropy.test(remote_data=True)'
      $ source deactivate

#. Build and test the Astropy wheels.  See the `wheel builder README
   <https://github.com/MacPython/astropy-wheels>`_ for instructions.  In
   summary, clone the wheel-building repo, edit the ``.travis.yml`` and
   ``appveyor.yml`` text files with the branch or commit for the release,
   commit and then push back up to github.  This will trigger a wheel build
   and test on OSX, Linux and Windows. Check the build has passed on on the
   Travis-CI interface at https://travis-ci.org/MacPython/astropy-wheels.
   You'll need commit privileges to the ``astropy-wheels`` repo; ask <NAME>
   or on the mailing list if you do not have them.

#. If the tests do *not* pass, you'll have to fix whatever the problem is.
   First you'll need to back out the release procedure by dropping the commits
   you made for release and removing the tag you created::

      $ git reset --hard HEAD^^^^ # you could also use the SHA hash of the commit before your first changelog edit
      $ git tag -d v<version>

#. Once the tests are all passing, it's time to actually proceed with the
   release! This has two steps:

   * build and upload the Astropy wheels;
   * make and upload the Astropy source release.


#. For the wheel build / upload, follow the `wheel builder README`_
   instructions again.  Edit the ``.travis.yml`` and ``appveyor.yml`` files
   to give the release tag to build.  Check the build has passed on on the
   Travis-CI interface at https://travis-ci.org/MacPython/astropy-wheels.  Now
   follow the instructions in the page above to download the built wheels to a
   local machine and upload to PyPI. If you use the ``wheel_download.py`` script,
   make sure you loop through all the available OS to get all the wheels.

#. Now the wheels are built and uploaded, you can upload the source release.
   For safety's sake, you may want to clean the repo yet again to make sure
   you didn't leave anything from the previous step::

      $ git clean -dfx
      $ cd astropy_helpers; git clean -dfx; cd ..

#. Upload the source distribution to PyPI; this is preceded by re-running
   the sdist command, which makes sure the source code is packaged up and ready
   to be uploaded. You also need to GPG sign the release, before using twine to
   upload it to PyPI. (You may need to install `twine`_ if you haven't used it yet)::

      $ python setup.py build sdist
      $ gpg --detach-sign -a dist/astropy-<version>.tar.gz
      $ twine upload dist/astropy-<version>*

#. Go to https://pypi.python.org/pypi?:action=pkg_edit&name=astropy
   and ensure that only the most recent releases in each actively maintained
   release line are *not* marked hidden.  For example, if v1.2.2 was
   just released, v1.2.1 should be hidden.  This is so that users only find
   the latest bugfix releases.

   Do not enabled "Auto-hide old releases" as that may hide bugfix releases
   from older release lines that we may still want to make available.

#. Push up these changes and the tag to the `astropy core repository`_::

      $ git push upstream v<version branch>.x
      $ git push upstream v<version branch>

   .. note::

      You may need to replace ``upstream`` here with ``astropy`` or
      whatever remote name you use for the `astropy core repository`_.
      Also, it might be tempting to use the ``--tags`` argument to ``git push``,
      but this should *not* be done, as it might push up some unintended tags.

#. If this is a release of the current release (i.e., not an LTS supported along
   side a more recent version), update the "stable" branch to point to the new
   release::

      $ git checkout stable
      $ git reset --hard v<version>
      $ git push upstream stable --force

#. Update Readthedocs so that it builds docs for the version you just released.
   You'll find this in the "admin" tab, with checkboxes next to each github tag.
   Also verify that the ``stable`` Readthedocs version builds correctly for
   the new version (it should trigger automatically once you've done the
   previous step).

#. When releasing a patch release, also set the previous RTD version in the
   release history to "protected".  For example when releasing v1.1.2, set
   v1.1.1 to "protected".  This prevents the previous releases from
   cluttering the list of versions that users see in the version dropdown
   (the previous versions are still accessible by their URL though).

#. Update the Astropy web site by editing the ``index.html`` page at
   https://github.com/astropy/astropy.github.com by changing the "current
   version" link and/or updating the list of older versions if this is an LTS
   bugfix or a new major version.  You may also need to update the contributor
   list on the web site if you updated the ``docs/credits.rst`` at the outset.

#. In the astropy *master* branch (not just the maintenance branch), be sure to
   update the ``CHANGES.rst`` to reflect the date of the release you just
   performed and to include the new section of the changelog.  Often the easiest
   way to do this is to use ``git cherry-pick`` the changelog commit just before
   the release commit from above. If you aren't sure how to do this, you might
   be better off just copying-and-pasting the relevant parts of the maintenance
   branch's ``CHANGES.rst`` into master.

#. 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.

#. Create a github milestone for the next bugfix version, move any remaining
   issues from the version you just released, and close the milestone. When
   releasing a major release, close the last milestone on the previous
   maintenance branch, too.

#. Notify the Conda Distribution Maintainer and the Continuous Integration
   maintainer about the new release.  Typically, you should wait to make sure
   ``conda-forge`` and possible ``conda`` works before sending out the public
   announcement (so that users that want to try out the new version can do
   so on conda).

#. Update the ``LATEST_ASTROPY_STABLE`` or ``ASTROPY_LTS_VERSION`` variables
   in the ``ci-helpers`` repository once the ``conda`` packages became
   available.


Modifications for a beta/release candidate release
--------------------------------------------------

   For major releases we do beta and/or release candidates to have a chance to
   catch significant bugs before the true release. If the release you are
   performing is this kind of pre-release, some of the above steps need to be
   modified.

   The primary modifications to the release procedure are:

   * When entering the new version number, instead of just removing the
     ``.dev``, enter "1.2b1" or "1.2rc1".  It is critical that you follow this
     numbering scheme (``x.yb#`` or ``x.y.zrc#``), as it will ensure the release
     is ordered "before" the main release by various automated tools, and also
     tells PyPI that this is a "pre-release".
   * Do *not* do the step of adding ``.dev`` in the "back to development" stage.
     If an RC goes well, there's no need for a "dev" stage, as the same version
     will be released with only minor doc updates, and strings like "x.yrcz.dev"
     confuse some version number parsing tools.
   * Do not do step #26 or later, as those are tasks for an actual release.


Performing a Feature Freeze/Branching new Major Versions
========================================================

As outlined in
`APE2 <https://github.com/astropy/astropy-APEs/blob/master/APE2.rst>`_, astropy
releases occur at regular intervals, but feature freezes occur well before the
actual release.  Feature freezes are also the time when the master branch's
development separates from the new major version's maintenance branch.  This
allows new development for the next major version to continue while the
soon-to-be-released version can focus on bug fixes and documentation updates.

The procedure for this is straightforward:

#. Update your local master branch to use to the latest version from github::

      $ git fetch upstream
      $ git checkout -B master upstream/master

#. Create a new branch from master at the point you want the feature freeze to
   occur::

      $ git branch v<version>.x

#. Update the ``VERSION`` in ``setup.py`` to reflect the new major version. For
   example, if you are about to issue a feature freeze for version ``1.2``, you
   will want to set the new version to ``'1.3.dev'``. Then add and commit that::

      <use your favorite editor on setup.py>
      $ git add setup.py
      $ git commit -m "Next major version: <next_version>"

#. Update the ``CHANGES.rst`` file with a new section at the very top for the
   next major version.  You will likely want to use the ``add_to_changelog.py``
   script in the `astropy-tools repository`_ for this. Then add and commit those
   changes::

      <use your favorite editor on CHANGES.rst>
      $ git add CHANGES.rst
      $ git commit -m "Add <next_version> to changelog"

#. Also update the "what's new" section of the docs to include a section for the
   next major version.  E.g.::

      $ cp docs/whatsnew/<current_version>.rst docs/whatsnew/<next_version>.rst

   You'll then need to edit ``docs/whatsnew/<next_version>.rst``, removing all
   the content but leaving the basic structure.  You may also need  to
   replace the "by the numbers" numbers with "xxx" as a reminder to update them
   before the next release. Then add the new version to the top of
   ``docs/whatsnew/index.rst``, update the reference in ``docs/index.rst`` to
   point to the that version, and commit these changes ::

      $ git add docs/whatsnew/<next_version>.rst
      $ git add docs/whatsnew/index.rst
      $ git add docs/index.rst
      $ git commit -m "Added <next_version> whats new section"

#. Push all of these changes up to github::

      $ git push upstream v<version>.x:v<version>.x
      $ git push upstream master:master

   .. note::

      You may need to replace ``upstream`` here with ``astropy`` or
      whatever remote name you use for the `astropy core repository`_.

#. On the github issue tracker, add a new milestone for the next major version.

#. Repeat the above steps for the astropy-helpers, using the same version series.

Maintaining Bug Fix Releases
============================

Astropy releases, as recommended for most Python projects, follows a
{'fraction_non_alphanumeric': 0.08068771563596301, 'fraction_numerical': 0.0023774317938012814, 'mean_word_length': 3.2788735888847538, 'pattern_counts': {'":': 0, '<': 79, '<?xml version=': 0, '>': 79, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '752201', 'n_tokens_mistral': 9616, 'n_tokens_neox': 9196, 'n_words': 4913}