NEXT_VER=NEXT_VERSION e.g. "0.8.0" (skip for PATCH releases)
Create a release branch
Create a release branch called "v${VER}-dev":
bash
git checkout -b "v${VER}-dev"
If you are doing a PATCH update, use `git cherry-pick` to integrate the commits
for the fixes you want to include in your update, making sure to resolve all
merge conflicts carefully:
bash
git cherry-pick <commit>
Bump the version number on the release branch:
bash
python dev_tools/modules.py replace_version --old ${VER}.dev0 --new ${VER}
git add .
git commit -m "Removing ${VER}.dev0 -> ${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}.dev0 --new ${NEXT_VER}.dev0
git add .
git commit -m "Bump cirq version to ${NEXT_VER}"
git push origin "version_bump_${NEXT_VER}"
The `main` branch should never see a non-dev version specifier.
Create the distribution wheel
From a 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](https://test.pypi.org) 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 MAY FAIL - PyPI might not have indexed the version yet
./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:
shell
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.
shell
git diff <previous version>..HEAD cirq-core/cirq/__init__.py
You can get the contributing authors for the release by running:
shell
git log <previous version>..HEAD --pretty="%an" | sort |\
uniq | sed ':a;N;$!ba;s/\n/, /g'
Release to production 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 Python 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 on GitHub
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 (meaning that
`NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES` is not empty in the file
[`dev_tools/notebooks/isolated_notebook_test.py`](dev_tools/notebooks/isolated_notebook_test.py)),
then follow the steps in our [notebooks guide](docs/dev/notebooks.md).
Verify the Zenodo archive
Each new release should get archived in Zenodo automatically. To check it, [log
in to Zenodo](https://zenodo.org) using credentials stored in Google's internal
password utility (or get someone from Google to do this). Navigate to the [list
of uploads](https://zenodo.org/me/uploads), and ensure an entry for the new
release is present there. Open the page for the entry, verify the information,
and edit it if necessary.
Email cirq-announce
Lastly, email cirq-announcegooglegroups.com with the release notes and an
announcement of the new version.
Finally, congratulate yourself on a release well done!