RELEASING.md

Releasing OpenTelemetry Packages (for maintainers only)

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
• Check PyPI
• Move stable tag
• Update main
• Hotfix procedure
• Troubleshooting
  • Publish failed

Checkout a clean repo

To avoid pushing untracked changes, check out the repo in a new dir

Update versions

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.

Create a new branch

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

Open a Pull Request

The PR should be opened from the release/<version> branch created as part of running prepare_release.sh in the steps above.

Create a Release

• 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)

Check PyPI

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

Move stable tag

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.

Update main

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

Hotfix procedure

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:

1. Identify the packages that are affected by the bug. Make the changes to those packages, merging to main, as quickly as possible.
2. On your local machine, remove the dev0 tags from the version number and increment the patch version number.
3. On your local machine, update CHANGELOG.md with the date of the hotfix change.
4. With administrator privileges for PyPi, manually publish the affected packages.
   1. Install twine and build
   2. Navigate to where the pyproject.toml file exists for the package you want to publish.
   3. To build the package: run python -m build.
   4. Validate your built distributions by running twine check dist/*.
   5. Upload distributions to PyPi by running twine upload dist/*.
5. Note that since hotfixes are manually published, the build scripts for publish after creating a release are not run.

Troubleshooting

Publish failed

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!