.. doctest-skip-all

****************************
Package Release Instructions
****************************

This document outlines the steps for releasing Photutils to `PyPI
<https://pypi.org/project/photutils/>`_. This process requires
admin-level access to the Photutils GitHub repository, as it relies on
the ability to push directly to the ``main`` branch.

These instructions assume the name of the git remote for the main
repository is called ``upstream``.

#. Check out the branch that you are going to release. This will usually
   be the ``main`` branch, unless you are making a release from a bugfix
   branch.

   To release from a bugfix branch, check out the ``A.B.x`` branch.
   Use ``git cherry-pick <hash>`` (or ``git cherry-pick -m1 <hash>``
   for merge commits) to backport fixes to the bugfix branch. Also, be
   sure to push all changes to the repository so that CI can run on the
   bugfix branch.

#. Ensure that a "What's New" page is added to the documentation for the
   new release. This page should be added to the ``docs/whats_new``
   directory and should be named ``<X.Y.Z>.rst``. Update the "What's
   New" link on the main page (``docs/index.rst``) to the new version.

#. Ensure that `CI tests <https://github.com/astropy/photutils/actions>`_
   are passing for the branch you are going to
   release. Also, ensure that `Read the Docs builds
   <https://app.readthedocs.org/projects/photutils/builds/>`_ are
   passing.

#. As an extra check, run the tests locally using ``tox`` to thoroughly
   test the code in isolated environments::

        tox -e test-alldeps -- --remote-data
        tox -e build_docs
        tox -e linkcheck

#. Update the ``CHANGES.rst`` file to make sure that all the changes are
   listed and update the release date from ``unreleased`` to the current
   date in ``yyyy-mm-dd`` format. Then commit the changes::

        git add CHANGES.rst
        git commit -m'Finalizing changelog for version <X.Y.Z>'

#. Create an annotated git tag (optionally signing with the ``-s``
   option) for the version number you are about to release::

        git tag -a <X.Y.Z> -m'<X.Y.Z>'
        git show <X.Y.Z>  # show the tag
        git tag  # show all tags

   .. _resume_release:

#. Optionally, :ref:`even more manual tests <manual_tests>` can be run.

#. Push this new tag to the upstream repo::

        git push upstream <X.Y.Z>

   The new tag will trigger the automated `Publish workflow
   <https://github.com/astropy/photutils/actions/workflows/publish.yml>`_
   to build the source distribution and wheels and upload them to `PyPI
   <https://pypi.org/project/photutils/>`_.

#. Create a `GitHub Release
   <https://github.com/astropy/photutils/releases>`_ by clicking on
   "Draft a new release", select the tag of the released version, add
   a release title with the released version, and add the following
   description::

        See the [changelog](https://photutils.readthedocs.io/en/stable/changelog.html) for release notes.

   Then click "Publish release". This step will trigger an automatic
   update of the package on Zenodo (see below).

#. Check that `Zenodo <https://doi.org/10.5281/zenodo.596036>`_
   is updated with the released version. Zenodo is already configured to
   automatically update with a new published GitHub Release (see above).

#. Open a new `GitHub Milestone
   <https://github.com/astropy/photutils/milestones>`_ for the next
   release. If there are any open issues or pull requests for the new
   released version, then move them to the next milestone. After there
   are no remaining open issues or pull requests for the released
   version then close its GitHub Milestone.

#. Go to `Read the Docs
   <https://app.readthedocs.org/projects/photutils/versions/>`_ and
   check that the "stable" docs correspond to the new released version.
   Hide any older released versions (i.e., check "Hidden").

#. Update ``CHANGES.rst``, adding new sections for the next ``x.y.z``
   version, e.g.,::

       x.y.z (unreleased)
       ------------------

       General
       ^^^^^^^

       New Features
       ^^^^^^^^^^^^

       Bug Fixes
       ^^^^^^^^^

       API Changes
       ^^^^^^^^^^^

   Then commit the changes and push to the upstream repo::

        git add CHANGES.rst
        git commit -m'Add version <x.y.z> to the changelog'
        git push upstream main

#. After the release, the conda-forge bot (``regro-cf-autotick-bot``)
   will automatically create a pull request to the `Photutils feedstock
   repository <https://github.com/conda-forge/photutils-feedstock>`_.
   The ``meta.yaml`` recipe may need to be edited to update
   dependencies or versions. Modify (if necessary), review,
   and merge the PR to create the `conda-forge package
   <https://anaconda.org/conda-forge/photutils>`_. The `Astropy conda
   channel <https://anaconda.org/astropy/photutils>`_ will automatically
   mirror the package from conda-forge.


.. _manual_tests:

Additional Manual Tests
-----------------------

These additional manual checks can be run before pushing the release tag
to the upstream repository.

#. Remove any untracked files (**WARNING: this will permanently remove
   any files that have not been previously committed**, so make sure that
   you don't need to keep any of these files)::

        git clean -dfx

#. Check out the release tag::

        git checkout <X.Y.Z>

#. Ensure the `build <https://pypi.org/project/build/>`_ and `twine
   <https://pypi.org/project/twine/>`_ packages are installed and up to
   date::

        pip install build twine --upgrade

#. Generate the source distribution tar file::

        python -m build --sdist .

   and perform a preliminary check of the tar file::

       python -m twine check --strict dist/*

#. Run tests on the generated source distribution by going inside the
   ``dist`` directory, expanding the tar file, going inside the expanded
   directory, and running the tests with::

        cd dist
        tar xvfz <file>.tar.gz
        cd <file>
        tox -e test-alldeps -- --remote-data
        tox -e build_docs

   Optionally, install and test the source distribution in a virtual
   environment::

        <install and activate virtual environment>
        pip install -e '.[all,test]'
        pytest --remote-data

   or::

        <install and activate virtual environment>
        pip install '../<file>.tar.gz[all,test]'
        cd <any-directory-outside-of-photutils-source>
        pytest --pyargs photutils --remote-data

#. Check out the ``main`` branch, go back to the package root directory,
   and remove the generated files with::

        git checkout main
        cd ../..
        git clean -dfx

#. Go back to the :ref:`release steps <resume_release>` where you left
   off.
