Releasing ESPEI¶
Use this checklist to create a new release of ESPEI and distribute the package
to PyPI and conda-forge. All steps are intended to be run from the root directory of the repository (i.e.
the one containing docs/
, espei/
, setup.py
, …).
Creating a new release¶
These steps will create a new tagged version in the GitHub repository.
git pull
to make sure you haven’t missed any last-minute commits. After this point, nothing else is making it into this version.pytest
to ensure that all tests pass locally.sphinx-apidoc -f -o docs/api/ espei/ -H 'API Documentation'
to regenerate API documentation.Commit the updated API documentation.
git push
and verify all tests pass on all CI services.Generate a list of commits since the last version with
git --no-pager log --oneline --no-decorate 0.1^..origin/master
. Replace0.1
with the tag of the last public version.Condense the change list into something user-readable. Update and commit
CHANGES.rst
with the release date.git tag 0.2 master -m "0.2"
Replace0.2
with the new version.git show 0.2
to ensure the correct commit was tagged.git push origin master --tags
to push the tag to GitHub.
Now the public package must be built and distributed.
Uploading to PyPI¶
All tagged GitHub commits should be uploaded to PyPI automatically by the
deploy.yaml
GitHub Action. If ESPEI needs to be released to PyPI manually,
follow the steps below.
Manually uploading to PyPI¶
rm -R dist/*
on Linux/OSX ordel dist/*
on Windows.python setup.py sdist
to create a source distribution.Make sure that the script correctly detected the new version exactly and not a dirty or revised state of the repository.
twine upload -r pypi -u bocklund dist/*
to upload to PyPI.
Updating the conda-forge feedstock¶
conda-forge is a community-developed platform for distributing packages to the conda-forge channel on Anaconda Cloud. Metadata for the packages are hosted in feedstocks and built using conda-build in a continuous integration pipeline.
conda-build is driven by a recipe/meta.yaml
configuration file, which
specifies the package metadata and dependencies. The meta.yaml
file is
updated via pull requests to the conda-forge/espei-feedstock. A pull request
is usually opened automatically by the conda-forge autotick bot, but pull
requests can be opened manually as well. Both methods are detailed below.
After updating the meta.yaml
file and merging the pull request, the
conda-forge continuous integration pipeline will run from the master branch and
upload build artifacts to the conda-forge channel on Anaconda Cloud. Uploaded
build artifacts are usually available to download and install in about 1 hour
after the continuous integration pipeline completes on the master branch.
The availability of a particular ESPEI package on conda-forge can be verified by
running conda search -c conda-forge --override-channels espei
.
conda-forge autotick bot (preferred)¶
The conda-forge autotick bot will automatically open a pull request in the conda-forge/espei-feedstock repository after the package has been uploaded to PyPI. This usually happens in less than 10 minutes after the PyPI release.
Verify that the
recipe/meta.yaml
requirements match the dependencies inenvironment-dev.yml
.Once all the checks pass, merge the pull request.
Manually updating¶
If the conda-forge autotick bot does not open a pull request automatically,
the conda-forge/espei-feedstock can still be updated manually with a pull
request that updates the recipe/meta.yaml
file.
Get the sha-256 hash of the tarball via
openssl sha256 dist/espei-0.3.1.tar.gz
or by viewing the hashes for the release at https://pypi.org/project/espei/#files.Fork the conda-forge/espei-feedstock repository.
Update the version number and hash in the
recipe/meta.yaml
file and set the build number to zero if the version number changed.Verify that the
recipe/meta.yaml
requirements match the dependencies inenvironment-dev.yml
.Open a PR against the conda-forge/espei-feedstock repository
Once all the checks pass, merge the pull request.