Skip to content

Latest commit

 

History

History
115 lines (91 loc) · 5.84 KB

RELEASING.rst

File metadata and controls

115 lines (91 loc) · 5.84 KB
Raw

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

Create a release of espei

To release a new version of espei:

These steps assume that 0.1 is the most recently tagged version number and 0.2 is the next version number to be released. Replace their values with the last public release's version number and the new version number as appropriate.

  1. Determine what the next version number should be using semantic versioning.
  2. Resolve or defer all pull requests and issues tagged with the upcoming version milestone.
  3. git stash to save any uncommitted work.
  4. git checkout master
  5. git pull to make sure you haven't missed any last-minute commits. After this point, nothing else is making it into this version.
  6. pytest to ensure that all tests pass locally.
  7. sphinx-apidoc -f -H 'API Documentation' -o docs/api/ espei to regenerate the API documentation.
  8. Update CHANGES.rst with a human-readable list of changes since the last commit. git log --oneline --no-decorate --color 0.1^..master can be used to list the changes since the last version.
  9. git add docs/api CHANGES.rst to stage the updated documentation.
  10. git commit -m "REL: 0.2" to commit the changes.
  11. git push origin master
  12. Verify that all continuous integration test and build workflows pass.
  13. Create a release on GitHub
    1. Go to https://github.com/phasesresearchlab/espei/releases/new
    2. Set the "Tag version" field to 0.2.
    3. Set the branch target to master.
    4. Set the "Release title" to espei 0.2.
    5. Leave the description box blank.
    6. If this version is a pre-release, check the "This is a pre-release" box.
    7. Click "Publish release".
  14. The new version will be available on PyPI when the Build and deploy to PyPI workflow on GitHub Actions finishes successfully.

Now the public package must be built and distributed.

Deploy to PyPI (manually)

Warning

DO NOT FOLLOW THESE STEPS unless the GitHub Actions deployment workflow is broken. Creating a GitHub release should trigger the Build and deploy to PyPI workflow on GitHub Actions that will upload source and platform-dependent wheel distributions automatically.

To release a source distribution to PyPI:

  1. If deploying for the first time: pip install twine build
  2. rm -R dist/* on Linux/OSX or del dist/* on Windows
  3. git checkout master to checkout the latest version
  4. git pull
  5. git log to verify the repository state matches the newly created tag
  6. python -m build --sdist
  7. Make sure that the script correctly detected the new version exactly and not a dirty / revised state of the repo.
  8. twine upload dist/* to upload (assumes a correctly configured ~/.pypirc file)

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.