This document explains how to publish all OT modules at version x.y.z. Ensure that you’re following semver when choosing a version number.
Release Process:
- Checkout a clean repo
- Update versions
- Create a new branch
- Open a Pull Request
- Create a Release
- Move stable tag
- Update main
- Update docs
- Check PyPI
- Troubleshooting
To avoid pushing untracked changes, check out the repo in a new dir
The update of the version information relies on the information in eachdist.ini to identify which packages are stable, prerelease or experimental. Update the desired version there to begin the release process.
The following script does the following:
- update main locally
- creates a new release branch
release/<version>
- updates version and changelog files
- commits the change
NOTE: This script was run by a GitHub Action but required the Action bot to be excluded from the CLA check, which it currently is not.
./scripts/prepare_release.sh
The PR should be opened from the release/<version>
branch created as part of running prepare_release.sh
in the steps above.
- Create the GH release from the main branch, using a new tag for this micro version, e.g.
v0.7.0
- Copy the changelogs from all packages that changed into the release notes (and reformat to remove hard line wraps)
This should be handled automatically on release by the publish action.
- Check the action logs to make sure packages have been uploaded to PyPI
- Check the release history (e.g. https://pypi.org/project/opentelemetry-api/#history) on PyPI
If for some reason the action failed, see Publish failed below
This will ensure the docs are pointing at the stable release.
git tag -d stable
git tag stable
git push --delete origin tagname
git push origin stable
To validate this worked, ensure the stable build has run successfully: https://readthedocs.org/projects/opentelemetry-python/builds/. If the build has not run automatically, it can be manually trigger via the readthedocs interface.
Ensure the version and changelog updates have been applied to main. Update the versions in eachdist.ini once again this time to include the .dev0
tag and
run eachdist once again:
./scripts/eachdist.py update_versions --versions stable,prerelease
A hotfix
is defined as a small change developed to correct a bug that should be released as quickly as possible. Due to the nature of hotfixes, they usually will only affect one or a few packages. Therefore, it usually is not necessary to go through the entire release process outlined above for hotfixes. Follow the below steps how to release a hotfix:
- Identify the packages that are affected by the bug. Make the changes to those packages, merging to
main
, as quickly as possible. - On your local machine, remove the
dev0
tags from the version number and increment the patch version number. - On your local machine, update
CHANGELOG.md
with the date of the hotfix change. - With administrator priviledges for PyPi, manually publish the affected packages.
a. Install twine
b. Navigate to where the
setup.py
file exists for the package you want to publish. c. Runpython setup.py sdist bdist_wheel
. You may have to install wheel as well. d. Validate your built distributions by runningtwine check dist/*
. e. Upload distibutions to PyPi by runningtwine upload dist/*
. - Note that since hotfixes are manually published, the build scripts for publish after creating a release are not run.
If for some reason the action failed, do it manually:
- Switch to the release branch (important so we don't publish packages with "dev" versions)
- Build distributions with
./scripts/build.sh
- Delete distributions we don't want to push (e.g.
testutil
) - Push to PyPI as
twine upload --skip-existing --verbose dist/*
- Double check PyPI!