Skip to content

RELEASING.md

Latest commit

 

History

History
96 lines (70 loc) · 4.53 KB

RELEASING.md

File metadata and controls

96 lines (70 loc) · 4.53 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.
  • 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
  • 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 and with the javaagent jar attached.
  • Lastly, if there were any change log updates in the release branch that need to be merged back to the main branch, the workflow will create a pull request if the updates can be cleanly applied, or it will fail this last step if the updates cannot be cleanly applied.

Update release versions in documentations and CHANGELOG files

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.

Next, update the CHANGELOG.md.

Create a PR to mark the new release in README.md and CHANGELOG.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}