Repository files navigation

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

It does so by parsing yourgit history, looking forConventional Commit messages,and creating release PRs.

It does not handle publication to package managers or handle complex branchmanagement.

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

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

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

1. Updates your changelog file (for exampleCHANGELOG.md), along with other language specific files (for examplepackage.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 thePR itself:

• autorelease: pending is the initial state of the Release PR before it is merged
• autorelease: tagged means that the Release PR has been merged and the release has been tagged in GitHub
• autorelease: snapshot is a special state for snapshot version bumps
• autorelease: published means that a GitHub release has been published based on the Release PR (release-please does not automatically add this tag, but we recommend it as a convention for publication tooling).

Release Please assumes you are usingConventional Commit messages.

The most important prefixes you should have in mind are:

• fix: which represents bug fixes, and correlates to aSemVerpatch.
• feat: which represents a new feature, and correlates to a SemVer minor.
• feat!:, orfix!:,refactor!:, etc., which represent a breaking change(indicated by the!) and will result in a SemVer major.

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

• Follow history - commits are sorted by merge date and are not mixed betweenpull requests
• Find and revert bugs -git bisect is helpful for tracking down whichchange introduced a bug
• Control the release-please changelog - when you merge a PR, you may havecommit messages that make sense within the scope of the PR, but don'tmake sense when merged in the main branch. For example, you may havefeat: introduce feature A and thenfix: some bugfix introduced in the first commit. Thefix commit is actually irrelevant to the releasenotes as there was never a bug experienced in the main branch.
• Keep a clean main branch - if you use something like red/green development(create a failing test in commit A, then fix in commit B) and merge (orrebase-merge), then there will be points in time in your main branch wheretests do not pass.

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

feat: adds v4 UUID to cryptoThis 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@5e0dcb2feat(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 notethat it's a breaking change.
3. an entry for the feature"update encode to support unicode".

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

When a commit to the main branch hasRelease-As: x.x.x (case insensitive) in thecommit 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.0Release-As: 2.0.0

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

BEGIN_COMMIT_OVERRIDEfeat: add ability to override merged commit messagefix: another messagechore: a third messageEND_COMMIT_OVERRIDE

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

⚠️Important: This feature will not work with plain merges becauserelease-please does not know which commit(s) to apply the override to.Werecommend using squash-merge instead.

Release Please creates a release pull request after it notices the default branchcontains "releasable units" since the last release.A releasable unit is a commit to the branch with one of the followingprefixes: "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.

Check existing pull requests labelled withautorelease: pending orautorelease: triggered label.Due to GitHub API failures, it's possible that the tag was not removedcorrectly upon a previous release and Release Please thinks that the previous release isstill pending.If you're certain that there's no pending release, remove theautorelease: pending orautorelease: triggered label.

For the GitHub application users, Release Please will not create a new pull requestif there's an existing pull request labeled asautorelease: 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 theautorelease: pending label and re-run ReleasePlease.

If you think Release Please missed creating a release PR after a pull requestwith a releasable unit has been merged, please re-runrelease-please. If you are usingthe GitHub application, addrelease-please:force-run label to the merged pull request. Ifyou 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.

Release Please automates releases for the following flavors of repositories:

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

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

Please seeRunning release-please CLI for all the configuration options.

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

Release Please provides several configuration options to allow customizingyour release process. Please seecustomizing.md for more details.

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

Our client libraries follow theNode.js release schedule.Libraries are compatible with all currentactive andmaintenance versions ofNode.js.

Client libraries targeting some end-of-life versions of Node.js are available, andcan be installed via npmdist-tags.The dist-tags follow the naming conventionlegacy-(version).

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

• Legacy versions will not be tested in continuous integration.
• Some security patches may not be able to be backported.
• Dependencies will not be kept up-to-date, and features will not be backported.

• legacy-8: install client libraries from this dist-tag for versionscompatible with Node.js 8.

This library followsSemantic Versioning.

Contributions welcome! See theContributing Guide.

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

For common issues and help troubleshooting your configuration, seeTroubleshooting.

Apache Version 2.0

SeeLICENSE

This is not an official Google product.