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.

  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 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/conf.py to the new version.

  5. Commit the updated API documentation and conf.py 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

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

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

  2. python setup.py 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 https://pypi.org/project/espei/#files.

  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.