Internal Note: Release procedure

Note

This page is an internal note for the developers.

The CHECKLIST for making a new release is as follows:

• Merge staging branch* into main
  • On the staging branch, UPDATE version in setup.py. It should follow the formats v1.2.3, v1.2.3-pre.4, or v1.2.3-post.4 depending on if it is a stable, pre-, or post-release. Our versioning policy is EffVer.
  • On the staging branch, UPDATE doc/source/changelog.rst
  • IF README.md or website homepage needs to be updated, UPDATE them**
  • CREATE PR to merge staging branch into main
  • VERIFY that the CI workflows for the PR have all finished and are passing
  • VERIFY that someone else has reviewed the PR
  • MERGE PR
• Make release on GitHub
  • CREATE a draft release
  • SET version number to the version number in setup.py
  • ADD content from changelog.rst to the release description, MODIFY as needed
  • Use the "Generate release notes" button to automatically CREATE a list of merged PRs since the last release
  • CHECK the "Set as a pre-release" and "Set as the latest release" checkboxes.
  • PUBLISH release
• Push package to PyPI
  • CHECKOUT to the main branch: git checkout main
  • PULL the latest updates; VERIFY if the newly merged contents are pulled: git pull origin main
  • VERIFY that you are at the flygym root level
  • REMOVE existing artifacts: rm -rf build dist flygym.egg-info
  • VERIFY that you are on the correct virtual environment
  • CREATE the wheels: python setup.py sdist bdist_wheel
  • VERIFY that ~/.pypirc contains a [flygym] entry with password set to a PyPI API key.
  • PUSH the package: python -m twine upload --repository flygym --verbose dist/*
  • IF authentication fails, check API key on pypi.org, and possibly REGENERATE one. UPDATE ~/.pypirc accordingly. Then, REPEAT the step above (PUSH the package).
• Push Docker image Docker Hub
  • (If not done already) AUTHENTICATE to Docker Hub: docker login
  • VERIFY that there are no files that should not be included in the image (except those captured by .dockerignore.
  • BUILD the image and tag it both as the latest version (default) and explicitly using the version number: docker build -t nelyepfl/flygym -t nelyepfl/flygym:vx.x.x . (replace version number)
  • PUSH to Docker Hub: docker push nelyepfl/flygym, then docker push nelyepfl/flygym:vx.x.x (replace version number)
• Cleaning up
  • REMOVE merged and deprecated branches

* The staging branch is the dev-vx.x.x[-pre/post.x] branch for development.

** If the overview video is updated, regenerate the GIF with ffmpeg -i overview_video.mp4 -vf "fps=15,scale=640:-1:flags=lanczos" -c:v gif overview_video.gif

So far I have not found it worth the time to automate this. Until it is, let's just use the checklist above.