.. doctest-skip-all
****************************
Package Release Instructions
****************************
This document outlines the steps for releasing Photutils to `PyPI
`_. 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 bugfix release.
For a bugfix release, check out the ``A.B.x`` branch. Use ``git
cherry-pick `` (or ``git cherry-pick -m1 `` 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 `CI tests `_
are passing for the branch you are going to
release. Also, ensure that `Read the Docs 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=any
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 '
#. Create an annotated git tag (optionally signing with the ``-s``
option) for the version number you are about to release::
git tag -a -m''
git show # show the tag
git tag # show all tags
#. Optionally, :ref:`even more manual tests ` can be run.
#. Push this new tag to the upstream repo::
git push upstream
The new tag will trigger the automated `Publish workflow
`_
to build the source distribution and wheels and upload them to `PyPI
`_.
#. Create a `GitHub Release
`_ 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 `_
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
`_ 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
`_ and check
that the "stable" docs correspond to the new released version. Hide
any older released versions (i.e., check "Hidden").
#. Update ``CHANGES.rst``. After releasing a minor (bugfix) version,
update its release date. After releasing a major version, add a new
section to ``CHANGES.rst`` 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 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 `_.
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
`_. The `Astropy conda
channel `_ 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
#. Ensure the `build `_ and `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 .tar.gz
cd
tox -e test-alldeps -- --remote-data=any
tox -e build_docs
Optionally, install and test the source distribution in a virtual
environment::
pip install -e '.[all,test]'
pytest --remote-data=any
or::
pip install '../.tar.gz[all,test]'
cd
python
>>> import photutils
>>> photutils.__version__
>>> photutils.test(remote_data=True)
#. Go back to the package root directory and remove the generated files
with::
git clean -dfx