Skip to content

Latest commit

 

History

History
109 lines (81 loc) · 5.39 KB

RELEASING.md

File metadata and controls

109 lines (81 loc) · 5.39 KB

OpenTelemetry Release Process

Before releasing, it is a good idea to run ./gradlew japicmp on the main branch and verify that there are no unexpected public API changes seen in the docs/apidiffs/current_vs_latest directory.

When preparing the change log, you can use git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x --graph --first-parent or the Github compare tool to view a summary of all commits since last release as a reference.

Preparing a new major or minor release

  • Close the release milestone if there is one.
  • Merge a pull request to main updating the CHANGELOG.md.
    • The heading for the release should include the release version but not the release date, e.g. ## Version 1.9.0 (Unreleased).
  • Run the Prepare release branch workflow.
  • Review and merge the two pull requests that it creates (one is targeted to the release branch and one is targeted to the main branch).

Preparing a new patch release

All patch releases should include only bug-fixes, and must avoid adding/modifying the public APIs.

In general, patch releases are only made for regressions, memory leaks and deadlocks.

  • Backport pull request(s) to the release branch.
    • Run the Backport workflow.
    • Press the "Run workflow" button, then select the release branch from the dropdown list, e.g. release/v1.9.x, then enter the pull request number that you want to backport, then click the "Run workflow" button below that.
    • Review and merge the backport pull request that it generates.
  • Merge a pull request to the release branch updating the CHANGELOG.md.
    • The heading for the release should include the release version but not the release date, e.g. ## Version 1.9.1 (Unreleased).
  • Run the Prepare patch release workflow.
    • Press the "Run workflow" button, then select the release branch from the dropdown list, e.g. release/v1.9.x, and click the "Run workflow" button below that.
  • Review and merge the pull request that it creates.

Making the release

Run the Release workflow.

  • Press the "Run workflow" button, then select the release branch from the dropdown list, e.g. release/v1.9.x, and click the "Run workflow" button below that.
  • This workflow will publish the artifacts to maven central and will publish a GitHub release with release notes based on the change log.
  • Review and merge the pull request that the release workflow creates against the release branch which adds the release date to the change log.

After the release

Run the Merge change log to main workflow.

  • Press the "Run workflow" button, then select the release branch from the dropdown list, e.g. release/v1.9.x, and click the "Run workflow" button below that.
  • This will create a pull request that merges the change log updates from the release branch back to main.
  • Review and merge the pull request that it creates.
  • This workflow will fail if there have been conflicting change log updates introduced in main, in which case you will need to merge the change log updates manually and send your own pull request against main.

Update release versions in documentations

After releasing is done, you need to first update the docs. This needs to happen after artifacts have propagated to Maven Central so should probably be done an hour or two after the release workflow finishes.

./gradlew updateVersionInDocs -Prelease.version=x.y.z
./gradlew japicmp -PapiBaseVersion=a.b.c -PapiNewVersion=x.y.z
./gradlew --refresh-dependencies japicmp

Where x.y.z is the version just released and a.b.c is the previous version.

Create a PR to mark the new release in README.md on the main branch.

Finally, update the website docs to refer to the newly released version.

Credentials

The following credentials are required for publishing (and automatically set in Circle CI):

  • GPG_PRIVATE_KEY and GPG_PASSWORD: GPG private key and password for signing

    • Note, currently only @anuraaga has this and we need to find a way to safely share secrets in the OpenTelemetry project, for example with a password manager. In the worst case if you need to release manually and cannot get a hold of it, you can generate a new key but don't forget to upload the public key to keyservers.

  • SONATYPE_USER and SONATYPE_KEY: Sonatype username and password.

Releasing from the local setup

Releasing from the local setup can be done providing the previously mentioned four credential values, i.e. GPG_PRIVATE_KEY, GPG_PASSWORD, SONATYPE_USER and SONATYPE_KEY:

export SONATYPE_USER=my_maven_user
export SONATYPE_KEY=my_maven_password
export GPG_PRIVATE_KEY=$(cat ~/tmp/gpg.key.txt)
export GPG_PASSWORD=<gpg password>
export RELEASE_VERSION=2.4.5 # Set version you want to release
./gradlew final -Prelease.version=${RELEASE_VERSION}