Home

Awesome

<img src="https://avatars2.githubusercontent.com/u/2810941?v=3&s=96" alt="Google Cloud Platform logo" title="Google Cloud Platform" align="right" height="96" width="96"/>

Release Please

npm version codecov

Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects.

It does so by parsing your git history, looking for Conventional Commit messages, and creating release PRs.

It does not handle publication to package managers or handle complex branch management.

What's a Release PR?

Rather than continuously releasing what's landed to your default branch, release-please maintains Release PRs:

<img width="400" src="/screen.png">

These Release PRs are kept up-to-date as additional work is merged. When you're ready to tag a release, simply merge the release PR. Both squash-merge and merge commits work with Release PRs.

When the Release PR is merged, release-please takes the following steps:

  1. Updates your changelog file (for example CHANGELOG.md), along with other language specific files (for example package.json).
  2. Tags the commit with the version number
  3. Creates a GitHub Release based on the tag

You can tell where the Release PR is in its lifecycle by the status label on the PR itself:

How should I write my commits?

Release Please assumes you are using Conventional Commit messages.

The most important prefixes you should have in mind are:

Linear git commit history (use squash-merge)

We highly recommend that you use squash-merges when merging pull requests. A linear git history makes it much easier to:

What if my PR contains multiple fixes or features?

Release Please allows you to represent multiple changes in a single commit, using footers:

feat: adds v4 UUID to crypto

This adds support for v4 UUIDs to the library.

fix(utils): unicode no longer throws exception
  PiperOrigin-RevId: 345559154
  BREAKING-CHANGE: encode method no longer throws.
  Source-Link: googleapis/googleapis@5e0dcb2

feat(utils): update encode to support unicode
  PiperOrigin-RevId: 345559182
  Source-Link: googleapis/googleapis@e5eef86

The above commit message will contain:

  1. an entry for the "adds v4 UUID to crypto" feature.
  2. an entry for the fix "unicode no longer throws exception", along with a note that it's a breaking change.
  3. an entry for the feature "update encode to support unicode".

:warning: Important: The additional messages must be added to the bottom of the commit.

How do I change the version number?

When a commit to the main branch has Release-As: x.x.x (case insensitive) in the commit body, Release Please will open a new pull request for the specified version.

Empty commit example:

git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0" results in the following commit message:

chore: release 2.0.0

Release-As: 2.0.0

How can I fix release notes?

If you have merged a pull request and would like to amend the commit message used to generate the release notes for that commit, you can edit the body of the merged pull requests and add a section like:

BEGIN_COMMIT_OVERRIDE
feat: add ability to override merged commit message

fix: another message
chore: a third message
END_COMMIT_OVERRIDE

The next time Release Please runs, it will use that override section as the commit message instead of the merged commit message.

:warning: Important: This feature will not work with plain merges because release-please does not know which commit(s) to apply the override to. We recommend using squash-merge instead.

Release Please bot does not create a release PR. Why?

Step 1: Ensure releasable units are merged

Release Please creates a release pull request after it notices the default branch contains "releasable units" since the last release. A releasable unit is a commit to the branch with one of the following prefixes: "feat", "fix", and "deps". (A "chore" or "build" commit is not a releasable unit.)

Some languages have their specific releasable unit configuration. For example, "docs" is a prefix for releasable units in Java and Python.

Step 2: Ensure no autorelease: pending or autorelease: triggered label in an old PR

Check existing pull requests labelled with autorelease: pending or autorelease: triggered label. Due to GitHub API failures, it's possible that the tag was not removed correctly upon a previous release and Release Please thinks that the previous release is still pending. If you're certain that there's no pending release, remove the autorelease: pending or autorelease: triggered label.

For the GitHub application users, Release Please will not create a new pull request if there's an existing pull request labeled as autorelease: pending. To confirm this case, search for a pull request with the label. (It's very likely it's the latest release pull request.) If you find a release pull request with the label and it is not going to be released (or already released), then remove the autorelease: pending label and re-run Release Please.

Step 3: Rerun Release Please

If you think Release Please missed creating a release PR after a pull request with a releasable unit has been merged, please re-run release-please. If you are using the GitHub application, add release-please:force-run label to the merged pull request. If you are using the action, look for the failed invocation and retry the workflow run. Release Please will process the pull request immediately to find releasable units.

Strategy (Language) types supported

Release Please automates releases for the following flavors of repositories:

release typedescription
bazelA Bazel module, with a MODULE.bazel and a CHANGELOG.md
dartA repository with a pubspec.yaml and a CHANGELOG.md
elixirA repository with a mix.exs and a CHANGELOG.md
goA repository with a CHANGELOG.md
helmA repository with a Chart.yaml and a CHANGELOG.md
javaA strategy that generates SNAPSHOT version after each release
krm-blueprintA kpt package, with 1 or more KRM files and a CHANGELOG.md
mavenStrategy for Maven projects, generates SNAPSHOT version after each release and updates pom.xml automatically
nodeA Node.js repository, with a package.json and CHANGELOG.md
expoAn Expo based React Native repository, with a package.json, app.json and CHANGELOG.md
ocamlAn OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md
phpA repository with a composer.json and a CHANGELOG.md
pythonA Python repository, with a setup.py, setup.cfg, CHANGELOG.md and optionally a pyproject.toml and a <project>/__init__.py
rubyA repository with a version.rb and a CHANGELOG.md
rustA Rust repository, with a Cargo.toml (either as a crate or workspace, although note that workspaces require a manifest driven release and the "cargo-workspace" plugin) and a CHANGELOG.md
sfdxA repository with a sfdx-project.json and a CHANGELOG.md
simpleA repository with a version.txt and a CHANGELOG.md
terraform-moduleA terraform module, with a version in the README.md, and a CHANGELOG.md

Setting up Release Please

There are a variety of ways you can deploy release-please:

GitHub Action (recommended)

The easiest way to run Release Please is as a GitHub action. Please see googleapis/release-please-action for installation and configuration instructions.

Running as CLI

Please see Running release-please CLI for all the configuration options.

Install the GitHub App

There is a probot application available, which allows you to deploy Release Please as a GitHub App. Please see github.com/googleapis/repo-automation-bots for installation and configuration instructions.

Bootstrapping your Repository

Release Please looks at commits since your last release tag. It may or may not be able to find your previous releases. The easiest way to onboard your repository is to bootstrap a manifest config.

Customizing Release Please

Release Please provides several configuration options to allow customizing your release process. Please see customizing.md for more details.

Supporting Monorepos via Manifest Configuration

Release Please also supports releasing multiple artifacts from the same repository. See more at manifest-releaser.md.

Supported Node.js Versions

Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js.

Client libraries targeting some end-of-life versions of Node.js are available, and can be installed via npm dist-tags. The dist-tags follow the naming convention legacy-(version).

Legacy Node.js versions are supported as a best effort:

Legacy tags available

Versioning

This library follows Semantic Versioning.

Contributing

Contributions welcome! See the Contributing Guide.

For more information on the design of the library, see design.

Troubleshooting

For common issues and help troubleshooting your configuration, see Troubleshooting.

License

Apache Version 2.0

See LICENSE

Disclaimer

This is not an official Google product.