Skip to content

Latest commit

 

History

History
135 lines (86 loc) · 6.47 KB

RELEASING.md

File metadata and controls

135 lines (86 loc) · 6.47 KB
Raw

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.

Auto-generate a Release PR

Navigate to the Create a Release PR Worflow. Click the "Run workflow" dropdown, enter the semver-compliant version to release, then click "Run workflow". It will generate a release pull request from a branch named like release/x.y.z.

Review Release PR

If necessary, update sample code or documentation on the release/x.y.z branch to be included in the release. Another maintainer should approve the PR, specifically validating the automatic updates and verifying the tests are passing.

NOTE: If any major changes are merged while the release PR is open, the CHANGELOG on the release/x.y.z branch must be manually updated to reflect the change.

Merge Release PR

After approval, merge the release PR. This will automatically publish all packages. Verify:

That's it! No need to read on unless something above went wrong.

Manual Publishing Process

If any step of the above automated process fails, complete the release manually by picking up at the failed step.

Manual Release Process Steps:

Update to latest locally

Use git fetch and git checkout origin/main to ensure you’re on the latest commit. Make sure you have no unstaged changes. Ideally, also use git clean -dfx to remove all ignored and untracked files.

Create a new branch

Create a new branch called x.y.z-proposal from the current commit.

Prepare each package for release

Decide on the next major.minor.patch release number based on semver guidelines.

  • Use npm install command to initialize all package directories
  • Use lerna publish --skip-npm --no-git-tag-version --no-push to bump the version in all package.json
  • Use npm run bootstrap to generate latest version.ts files

Use the Changelog to create a GitHub Release

Generate the changelog with lerna

Since we use lerna, we can use lerna-changelog

How to use

Pass your github token to generate the changelog automatically. For security reasons, when you create a Github token, select the permissions: under repo, select Access public repositories, commit status.

In your terminal, execute the following command:

GITHUB_AUTH=<your token> lerna-changelog

It will print something like:

## Unreleased (2018-05-24)

#### :bug: Bug Fix
* [#198](https://github.com/my-org/my-repo/pull/198) Avoid an infinite loop ([@helpful-hacker](https://github.com/helpful-hacker))

#### :house: Internal
* [#183](https://github.com/my-org/my-repo/pull/183) Standardize error messages ([@careful-coder](https://github.com/careful-coder))

#### Commiters: 2
- Helpful Hacker ([@helpful-hacker](https://github.com/helpful-hacker))
- [@careful-coder](https://github.com/careful-coder)

By default lerna-changelog will show all pull requests that have been merged since the latest tagged commit in the repository. That is however only true for pull requests with certain labels applied (see lerna.json for authorized labels).

You can also use the --from and --to options to view a different range of pull requests:

GITHUB_AUTH=xxxxx lerna-changelog --from=v1.0.0 --to=v2.0.0

Update Changelog file

From what lerna-changelog has generated, starts new Unreleased label. Follow the example set by recent Released label.

On GitHub Releases, follow the example set by recent releases to populate a summary of changes, as well as a list of commits that were applied since the last release. Save it as a draft, don’t publish it. Don’t forget the tag -- call it vx.y.z and leave it pointing at main for now (this can be changed as long as the GitHub release isn’t published).

Create a new PR

Create a pull request titled chore: x.y.z release proposal. The commit body should just be a link to the draft notes. Someone who can access draft notes should approve it, looking in particular for test passing, and whether the draft notes are satisfactory.

Merge and pull

Merge the PR, and pull the changes locally (using the commands in the first step). Ensure that chore: x.y.z release proposal is the most recent commit.

Publish all packages

Go into each directory and use npm publish (requires permissions) to publish the package. You can use the following script to automate this.

#!/bin/bash

for dir in $(ls packages); do
 pushd packages/$dir
 npm publish
 popd
done

Check your e-mail and make sure the number of “you’ve published this module” emails matches the number you expect.

Publish the GitHub Release

Publish the GitHub release, ensuring that the tag points to the newly landed commit corresponding to release proposal x.y.z.

Update CHANGELOG

  • After releasing is done, update the CHANGELOG.md and start new Unreleased label.
  • Create a new commit with the exact title: Post Release: update CHANGELOG.md.
  • Go through PR review and merge it to GitHub main branch.

Known Issues

  • The examples/ and getting-started/ folders are not part of lerna packages, we need to manually bump the version in package.json.