NEXT_VER=NEXT_VERSION e.g. "0.8.0" (skip for PATCH releases)
Create release branch
Create a release branch called "v${VERSION}-dev":
bash
git checkout -b "v${VER}-dev"
If you are doing a PATCH update, also cherrypick the commits for the fixes
you want to include in your update and resolve all potential merge conflicts
carefully:
bash
git cherry-pick <commit>
Bump the version on the release branch:
bash
python dev_tools/modules.py replace_version --old ${VER}.dev --new ${VER}
git add .
git commit -m "Removing ${VER}.dev -> ${VER}"
git push origin "v${VER}-dev"
Bump the main version
WARNING: Only bump the main version for minor and major releases, for PATCH
updates, leave it as it is.
bash
git checkout main -b "version_bump_${NEXT_VER}"
python dev_tools/modules.py replace_version --old ${VER}.dev --new ${NEXT_VER}.dev
git add .
git commit -m "Bump cirq version to ${NEXT_VER}"
git push origin "version_bump_${NEXT_VER}"
Master branch should never see a non-dev version specifier.
Create distribution wheel
From release branch, create a binary distribution wheel. This is the package
that will go to pypi.
bash
git checkout "v${VER}-dev"
./dev_tools/packaging/produce-package.sh dist
ls dist should only contain one file, for each modules
Push to test pypi
The package server pypi has a test server where packages can be uploaded to
check that they work correctly before pushing the real version. This section
illustrates how to upload the package to test pypi and verify that it works.
First, upload the package in the dist/ directory. (Ensure that this is the only
package in this directory, or modify the commands to upload only this
file).
bash
twine upload --repository-url=https://test.pypi.org/legacy/ -u="$TEST_TWINE_USERNAME" -p="$TEST_TWINE_PASSWORD" "dist/*"
Next, run automated verification.
Note: sometimes the first verification from test pypi will fail.
bash
NOTE: FIRST RUN WILL LIKELY FAIL - pypi might not have yet indexed the version
./dev_tools/packaging/verify-published-package.sh "${VER}" --test
Once this runs, you can create a virtual environment to perform
manual verification as a sanity check and to check version number and
any high-risk features that have changed this release.
bash
mkvirtualenv "verify_test_${VER}" --python=/usr/bin/python3
pip install -r dev_tools/requirements/dev.env.txt
pip install --index-url=https://test.pypi.org/simple/ cirq=="${VER}"
python -c "import cirq; print(cirq.__version__)"
python just do some stuff checking that latest features are present
Draft release notes and email
Put together a release notes document that can be used as part of a
release and for an announcement email.
You can model the release notes on the previous release from the
[Release page](https://github.com/quantumlib/Cirq/releases).
1. Fill out the new version in "Tag Version" and choose your release
branch to create the tag from.
2. Attach the generated whl file to the release
Retrieve all commits since the last release with:
git log "--pretty=%h %s".
You can get the changes to the top-level objects and protocols by
checking the history of the init files. `git diff <previous version>..HEAD cirq-core/cirq/__init__.py`
You can get the contributing authors for the release by running:
`git log <previous version>..HEAD --pretty="%an" | sort | uniq | sed ':a;N;$!ba;s/\n/, /g'`
cirq-google Changelog
Add cirq-google release notes to `cirq-google/CHANGELOG.md` following the [changelog format](https://keepachangelog.com/en/1.0.0/)
Release to prod pypi
Upload to prod pypi using the following command:
bash
twine upload --username="$PROD_TWINE_USERNAME" --password="$PROD_TWINE_PASSWORD" "dist/*"
Perform automated verification tests:
bash
NOTE: FIRST RUN WILL LIKELY FAIL - pypi might not have yet indexed the version
./dev_tools/packaging/verify-published-package.sh "${VER}" --prod
Next, create a virtual environment to perform manual verification of the
release.
bash
mkvirtualenv "verify_${VER}" --python=/usr/bin/python3
pip install cirq
python -c "import cirq; print(cirq.__version__)"
Create the release
Using the information above, create the release on the
[Release page](https://github.com/quantumlib/Cirq/releases).
Be sure to include the whl file as an attachment.
Release PR for notebooks
If there are unreleased notebooks, that are under testing (`NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES` is not empty in [dev_tools/notebooks/isolated_notebook_test.py](dev_tools/notebooks/isolated_notebook_test.py)), follow the steps in our [notebooks guide](docs/dev/notebooks.md).
Create zenodo release
Got to the [Zenodo release page](https://zenodo.org/record/6599601#.YpZCspPMLzc).
Login using credentials within Google's internal password utility (or get
someone from Google to do this). Click "New Version".
* Upload the new zip file (found in releases page under "assets").
* Remove old zip file.
* Update version.
* Double check all other fields.
* Click publish.
Email cirq-announce
Lastly, email cirq-announcegooglegroups.com with the release notes
and an announcement of the new version.
Congratulate yourself for a well done release!