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 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 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
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
```
Optionally, even more 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 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, 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. 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.

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 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 <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 release steps where you left off.