Releasing a new version of Mitiq#
These instructions are for Mitiq maintainers. Releasing a new version of Mitiq is typically performed by the milestone manager whose responsibilities are detailed here.
When the time is ready for a new release, follow the checklist and instructions of this document to go through all the steps below:
The start of any release is drafting the changelog and bumping the version number. Ensure the commit where these changes are made include authorship for all contributors for the given milestone (code, or not). (Co-authored commits can be created by following the documentation here.)
This task has two parts:
Make sure that
CHANGELOG.mdhas an entry for each pull request (PR) since the last release. This can be generated from the commit history using
git log vX.Y.Z.. --pretty=format:"- %s [%an]"where
vX.Y.Zis the last version of mitiq which was released. The author names need to then be replaced with the author’s GitHub handle. An example might look like
- Update python-rapidjson requirement from <=1.6 to <1.8 (#1389) [@dependabot[bot]]once completed.
The release author should add a “Summary” section with a couple sentences describing the latest release, and then update the title of the release section to include the release date and remove the “In Development” designation.
When releasing a new version, one must update the
which is the single source of truth for version information. We follow
SemVer, so typically a release will involve changing the version from
vX.Y.Zdev (development) to
Once the above changes (new changelog and new version) are merged into
the master branch, checkout and pull the latest on the master branch
from your local machine. Then once you are up to date, tag the most
recent commit on master (using
git tag) with a tag that matches the
VERSION.txt (with a preceding “v”, so
and push this tag to the Github repository.
git tag v0.1.0 git push origin v0.1.0
You need to have write access to the Mitiq Github repository to make a new release.
GitHub will create compressed files with the repository.
GitHub adds the full changelog in the draft release. Please keep the content related to the new release and remove the content related to previous releases.
If all the above steps have been successfully completed, ReadTheDocs
(RTD) will automatically build new
stable versions of the
documentation. So, no additional steps are needed for updating RTD. You
can verify changes have been updating by viewing
https://mitiq.readthedocs.io/. Note that this may require a
significant amount of time. You can check the build status
Once the GitHub release is published, the release is also published on PyPI by the publish-pypi action. This may require a few minutes. If it seems like it didn’t push a new version to PyPI, you can trigger it manually. Go to unitaryfund/mitiq and use the “Run Workflow” button to publish the new version on PyPI.
In case the action for releasing on PyPI fails, the Python commands to release Mitiq are:
python -m pip install --upgrade pip make install requirements pip install setuptools wheel twine python setup.py sdist bdist_wheel twine upload dist/*
You need to be a registered maintainer of Mitiq project on PyPI to upload a new release on PyPI from your local machine.
Add a new section to the
CHANGELOG.md to track changes in the following release, meaning that if
vX.Y.Z was just released, then there should be a section for
vX.(Y+1).0 that is marked “In Development”.
Finally, change the version in