opentelemetry-js/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:

• Update to latest locally
• Create a new branch
• Prepare each package for release
• Use the Changelog to create a GitHub Release
• Create a new PR
• Merge and pull
• Publish all packages
• Publish the GitHub Release
• Update CHANGELOG

Update to latest locally

Use git fetch and git checkout origin/master 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 master 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 master 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.