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
These instructions assume the name of the git remote for the main
repository is called
Check out the branch that you are going to release. This will usually be the
mainbranch, unless you are making a bugfix release.
For a bugfix release, check out the
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.
As an extra check, run the tests locally using
toxto thoroughly test the code in isolated environments:
tox -e test-alldeps -- --remote-data=any tox -e build_docs tox -e linkcheck
CHANGES.rstfile to make sure that all the changes are listed and update the release date from
unreleasedto the current date in
yyyy-mm-ddformat. 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
-soption) 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>
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. Deactivate any older released versions (i.e., uncheck “Active”).
After the release, the conda-forge bot (
regro-cf-autotick-bot) will automatically create a pull request to the Photutils feedstock repository. The
meta.yamlrecipe 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.
CHANGES.rst. After releasing a minor (bugfix) version, update its release date. After releasing a major version, add a new section to
CHANGES.rstfor the next
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 releasing a major version, tag this new commit with the development version of the next major version and push the tag to the upstream repo. This is needed if the latest package release is the first bugfix release tagged on a bugfix branch (not the main branch):
git tag -a <x.y.z.dev> -m'<x.y.z.dev>' git push upstream <x.y.z.dev>
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>
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
distdirectory, 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=any 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=any
<install and activate virtual environment> pip install '../<file>.tar.gz[all,test]' cd <any-directory-outside-of-photutils-source> 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