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

The automated portion of the Astropy release procedure uses `zest.releaser`_
to create the tag and update the version.  zest.releaser is extendable through
hook functions--Astropy already includes a couple hook functions to modify the
default behavior, but future releases may be further automated through the
implementation of additional hook functions.  In order to use the hooks,
Astropy itself must be *installed* alongside zest.releaser.  It is recommended
to create a `virtualenv`_ specifically for this purpose.

This may seem like a lot of steps, but most of them won't be necessary to
repeat for each release.  The advantage of using an automated or semi-automated
procedure is that ensures a consistent release process each time.

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

 2. Update the list of contributors in the ``creditsandlicense.rst`` file. The
    easiest way to check this is do::

        $ git shortlog -s

    And just add anyone from that list who isn't already credited.

 3. Install virtualenv if you don't already have it.  See the linked virtualenv
    documentation for details.  Also, make sure that you have `cython`_
    installed, as you will need it to generate the .c files needed for the
    release.

 4. Create and activate a virtualenv::

        $ virtualenv --system-site-packages astropy-release
        $ source astropy-release/bin/activate

 5. Obtain a *clean* version of the Astropy repository.  That is, one
    where you don't have any intermediate build files.  Either use a fresh
    ``git clone`` or do ``git clean -dfx``.

 6. Be sure you're the "master" branch or, for a bug fix release, on the
    appropriate bug fix branch.  For example, if releasing version 0.2.2 make
    sure to::

        $ git checkout v0.2.x

 7. Now install Astropy into the virtualenv::

        $ python setup.py install

    This is necessary for two reasons.  First, the entry points for the
    releaser scripts need to be available, and these are in the Astropy
    package. Second, the build process will generate .c files from the
    Cython .pyx files, and the .c files are necessary for the source
    distribution.

 8. Install zest.releaser into the virtualenv; use ``--upgrade --force`` to
    ensure that the latest version is installed in the virtualenv (if you're
    running a csh variant make sure to run ``rehash`` afterwards too)::

        $ pip install zest.releaser==3.49 --upgrade --force

    .. note::

        zest.releaser > 3.49 has a still open issue that prevents our release
        code from correctly updating the ``VERSION`` variable in our ``setup.py``;
        see `zestsoftware/zest.releaser#62 <https://github.com/zestsoftware/zest.releaser/pull/62>`_.

 9. Ensure that all changes to the code have been committed, then start the
    release by running::

        $ fullrelease

 10. You will be asked to enter the version to be released.  Press enter to
     accept the default (which will normally be correct) or enter a specific
     version string.  A diff will then be shown of CHANGES.rst and setup.py
     showing that a release date has been added to the changelog, and that the
     version has been updated in setup.py.  Enter 'Y' when asked to commit
     these changes.

 11. You will then be shown the command that will be run to tag the release.
     Enter 'Y' to confirm and run the command.

 12. When asked "Check out the tag (for tweaks or pypi/distutils server
     upload)" enter 'N': zest.releaser does not offer enough control yet over
     how the register and upload are performed so we will do this manually
     until the release scripts have been improved.

 13. You will be asked to enter a new development version.  Normally the next
     logical version will be selected--press enter to accept the default, or
     enter a specific version string.  Do not add ".dev" to the version, as
     this will be appended automatically (ignore the message that says ".dev0
     will be appended"--it will actually be ".dev" without the 0).  For
     example, if the just-released version was "0.1" the default next version
     will be "0.2".  If we want the next version to be, say "0.1.1", or "1.0",
     then that must be entered manually.

 14. You will be shown a diff of CHANGES.rst showing that a new section has
     been added for the new development version, and showing that the version
     has been updated in setup.py.  Enter 'Y' to commit these changes.

 15. When asked to push the changes to a remote repository, enter 'Y'.  This
     should complete the portion of the process that's automated at this point.

 16. Check out the tag of the released version.  For example::

         $ git checkout v0.1

 17. Create the source distribution by doing::

         $ git clean -dfx  # just in case
         $ python setup.py build sdist

     Copy the produced ``.tar.gz`` somewhere and verify that you can unpack it,
     build it, and get all the tests to pass.  It would be best to create a new
     virtualenv in which to do this.

     .. note::

         In the future, the ``build`` command should 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.

 18. Register the release on PyPI with::

         $ python setup.py register

 19. Upload the source distribution to PyPI; this is preceded by re-running
     the sdist command, which is necessary for the upload command to know
     which distribution to upload::

         $ python setup.py build sdist upload --sign

 20. 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 v0.3.1 was
     just released, v0.3 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.

 21. Update the "stable" branch to point to the new stable release For example::

         $ git checkout stable
         $ git reset --hard v0.1
         $ git push origin stable --force

 22. Update Readthedocs so that it builds docs for the corresponding 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.)

 23. If this was a major/minor release (not a bug fix release) create a bug fix
     branch for this line of release.  That is, if the version just released<commit_msg>Add note to release notes about setting previous releases as 'protected' on RTD [skip ci]<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
-----------------

The automated portion of the Astropy release procedure uses `zest.releaser`_
to create the tag and update the version.  zest.releaser is extendable through
hook functions--Astropy already includes a couple hook functions to modify the
default behavior, but future releases may be further automated through the
implementation of additional hook functions.  In order to use the hooks,
Astropy itself must be *installed* alongside zest.releaser.  It is recommended
to create a `virtualenv`_ specifically for this purpose.

This may seem like a lot of steps, but most of them won't be necessary to
repeat for each release.  The advantage of using an automated or semi-automated
procedure is that ensures a consistent release process each time.

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

 2. Update the list of contributors in the ``creditsandlicense.rst`` file. The
    easiest way to check this is do::

        $ git shortlog -s

    And just add anyone from that list who isn't already credited.

 3. Install virtualenv if you don't already have it.  See the linked virtualenv
    documentation for details.  Also, make sure that you have `cython`_
    installed, as you will need it to generate the .c files needed for the
    release.

 4. Create and activate a virtualenv::

        $ virtualenv --system-site-packages astropy-release
        $ source astropy-release/bin/activate

 5. Obtain a *clean* version of the Astropy repository.  That is, one
    where you don't have any intermediate build files.  Either use a fresh
    ``git clone`` or do ``git clean -dfx``.

 6. Be sure you're the "master" branch or, for a bug fix release, on the
    appropriate bug fix branch.  For example, if releasing version 0.2.2 make
    sure to::

        $ git checkout v0.2.x

 7. Now install Astropy into the virtualenv::

        $ python setup.py install

    This is necessary for two reasons.  First, the entry points for the
    releaser scripts need to be available, and these are in the Astropy
    package. Second, the build process will generate .c files from the
    Cython .pyx files, and the .c files are necessary for the source
    distribution.

 8. Install zest.releaser into the virtualenv; use ``--upgrade --force`` to
    ensure that the latest version is installed in the virtualenv (if you're
    running a csh variant make sure to run ``rehash`` afterwards too)::

        $ pip install zest.releaser==3.49 --upgrade --force

    .. note::

        zest.releaser > 3.49 has a still open issue that prevents our release
        code from correctly updating the ``VERSION`` variable in our ``setup.py``;
        see `zestsoftware/zest.releaser#62 <https://github.com/zestsoftware/zest.releaser/pull/62>`_.

 9. Ensure that all changes to the code have been committed, then start the
    release by running::

        $ fullrelease

 10. You will be asked to enter the version to be released.  Press enter to
     accept the default (which will normally be correct) or enter a specific
     version string.  A diff will then be shown of CHANGES.rst and setup.py
     showing that a release date has been added to the changelog, and that the
     version has been updated in setup.py.  Enter 'Y' when asked to commit
     these changes.

 11. You will then be shown the command that will be run to tag the release.
     Enter 'Y' to confirm and run the command.

 12. When asked "Check out the tag (for tweaks or pypi/distutils server
     upload)" enter 'N': zest.releaser does not offer enough control yet over
     how the register and upload are performed so we will do this manually
     until the release scripts have been improved.

 13. You will be asked to enter a new development version.  Normally the next
     logical version will be selected--press enter to accept the default, or
     enter a specific version string.  Do not add ".dev" to the version, as
     this will be appended automatically (ignore the message that says ".dev0
     will be appended"--it will actually be ".dev" without the 0).  For
     example, if the just-released version was "0.1" the default next version
     will be "0.2".  If we want the next version to be, say "0.1.1", or "1.0",
     then that must be entered manually.

 14. You will be shown a diff of CHANGES.rst showing that a new section has
     been added for the new development version, and showing that the version
     has been updated in setup.py.  Enter 'Y' to commit these changes.

 15. When asked to push the changes to a remote repository, enter 'Y'.  This
     should complete the portion of the process that's automated at this point.

 16. Check out the tag of the released version.  For example::

         $ git checkout v0.1

 17. Create the source distribution by doing::

         $ git clean -dfx  # just in case
         $ python setup.py build sdist

     Copy the produced ``.tar.gz`` somewhere and verify that you can unpack it,
     build it, and get all the tests to pass.  It would be best to create a new
     virtualenv in which to do this.

     .. note::

         In the future, the ``build`` command should 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.

 18. Register the release on PyPI with::

         $ python setup.py register

 19. Upload the source distribution to PyPI; this is preceded by re-running
     the sdist command, which is necessary for the upload command to know
     which distribution to upload::

         $ python setup.py build sdist upload --sign

 20. 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 v0.3.1 was
     just released, v0.3 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.

 21. Update the "stable" branch to point to the new stable release For example::

         $ git checkout stable
         $ git reset --hard v0.1
         $ git push origin stable --force

 22. Update Readthedocs so that it builds docs for the corresponding 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 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).

 23. If this was a major/minor release (not a bug fix release) create a bug fix
     branch for this line of release.  That is, if the version just released
{'fraction_non_alphanumeric': 0.061312783073075104, 'fraction_numerical': 0.010139931048468871, 'mean_word_length': 2.971543624161074, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5261496', 'n_tokens_mistral': 3958, 'n_tokens_neox': 3688, 'n_words': 2172}