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/,, …).

Creating a new release

These steps will create a new tagged version in the GitHub repository.

  1. git pull to make sure you haven’t missed any last-minute commits. After this point, nothing else is making it into this version.

  2. pytest -v --doctest-modules espei tests to ensure that all tests pass locally.

  3. sphinx-apidoc -f -o docs/api/ espei/ -H 'API Documentation' to regenerate API documentation.

  4. Update the version and release variables of docs/ to the new version.

  5. Commit the updated API documentation and file.

  6. git push and verify all tests pass on all CI services.

  7. Generate a list of commits since the last version with git --no-pager log --oneline --no-decorate 0.1^..origin/master. Replace 0.1 with the tag of the last public version.

  8. Condense the change list into something user-readable. Update and commit CHANGES.rst with the release date.

  9. git tag 0.2 master -m "0.2" Replace 0.2 with the new version.

  10. git show 0.2 to ensure the correct commit was tagged.

  11. git push origin master --tags to push the tag to GitHub.

Now the public package must be built and distributed.

Uploading to PyPI

  1. rm -R dist/* on Linux/OSX or del dist/* on Windows.

  2. python sdist to create a source distribution.

  3. Make sure that the script correctly detected the new version exactly and not a dirty or revised state of the repository.

  4. 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)

  1. 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.

  2. Verify that the recipe/meta.yaml requirements match the dependencies in environment-dev.yml.

  3. 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.

  1. 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

  2. Fork the conda-forge/espei-feedstock repository.

  3. Update the version number and hash in the recipe/meta.yaml file and set the build number to zero if the version number changed.

  4. Verify that the recipe/meta.yaml requirements match the dependencies in environment-dev.yml.

  5. Open a PR against the conda-forge/espei-feedstock repository

  6. Once all the checks pass, merge the pull request.