$ npm install release-please
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.
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'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:
CHANGELOG.md
), along with other language specific files (for example package.json
).You can tell where the Release PR is its lifecycle by the status label on the PR itself:
autorelease:pending
is the initial state of the Release PR before it is mergedautorelease:tagged
means that the Release PR has been merged and the release has been tagged in GitHubautorelease: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 using Conventional Commit messages.
The most important prefixes you should have in mind are:
fix:
which represents bug fixes, and correlates to a SemVer
patch.feat:
which represents a new feature, and correlates to a SemVer minor.feat!:
, or fix!:
, refactor!:
, etc., which represent a breaking change
(indicated by the !
) and will result in a SemVer major.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:
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
Release Please automates releases for the following flavors of repositories:
release type | description |
---|---|
node | A Node.js repository, with a package.json and CHANGELOG.md |
python | A Python repository, with a setup.py, setup.cfg, CHANGELOG.md and optionally a pyproject.toml and a <project>/__init__.py |
terraform-module | A terraform module, with a version in the README.md, and a CHANGELOG.md |
krm-blueprint | A kpt package, with 1 or more KRM files and a CHANGELOG.md |
rust | A Rust repository, with a Cargo.toml (either as a crate or workspace) and a CHANGELOG.md |
ocaml | An OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md |
simple | A repository with a version.txt and a CHANGELOG.md |
helm | A repository with a Chart.yaml and a CHANGELOG.md |
elixir | A repository with a mix.exs and a CHANGELOG.md |
dart | A repository with a pubspec.yaml and a CHANGELOG.md |
To add a new release type, simply use the existing releasers and updaters as a starting point.
releasers describe the files that should be updated for a release.
updaters describe how to update the version in these files.
There are a variety of ways you can deploy release-please:
The easiest way to run release please is as a GitHub action:
If you haven't already done so, create a .github/workflows
folder in your
repository (this is where your actions will live).
Now create a .github/workflows/release-please.yml
file with these contents:
on:
push:
branches:
- main
name: release-please
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: GoogleCloudPlatform/release-please-action@v2
with:
token: ${{ secrets.GITHUB_TOKEN }}
release-type: node
package-name: release-please-action
Merge the above action into your repository and make sure new commits follow the Conventional Commits convention, release-please will start creating Release PRs for you.
With a few additions, the Release Please action can be made to publish to npm when a Release PR is merged:
on:
push:
branches:
- main
name: release-please
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: GoogleCloudPlatform/release-please-action@v2
id: release
with:
token: ${{ secrets.GITHUB_TOKEN }}
release-type: node
package-name: test-release-please
# The logic below handles the npm publication:
- uses: actions/checkout@v2
# these if statements ensure that a publication only occurs when
# a new release is created:
if: ${{ steps.release.outputs.release_created }}
- uses: actions/setup-node@v1
with:
node-version: 12
registry-url: 'https://registry.npmjs.org'
if: ${{ steps.release.outputs.release_created }}
# if you are using Yarn, substitute the command below with `yarn install --frozen-lockfile`
- run: npm ci
if: ${{ steps.release.outputs.release_created }}
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
if: ${{ steps.release.outputs.release_created }}
So that you can keep 2FA enabled for npm publications, we recommend setting
registry-url
to your own Wombat Dressing Room deployment.
Install release-please globally:
npm i release-please -g
release-please release-pr --package-name=@google-cloud/firestore" \
--repo-url=googleapis/nodejs-firestore \
--token=$GITHUB_TOKEN
option | description |
---|---|
--package-name |
is the name of the package to publish to publish to an upstream registry such as npm. |
--repo-url |
is the URL of the repository on GitHub. |
--token |
a token with write access to --repo-url . |
--default-branch |
branch to open pull release PR against (detected by default). |
--path |
create a release from a path other than the repository's root |
--monorepo-tags |
add prefix to tags and branches, allowing multiple libraries to be released from the same repository. |
--pull-request-title-pattern |
add title pattern to make release PR, defaults to using chore${scope}: release${component} ${version} . |
--signoff |
Add Signed-off-by line at the end of the commit log message using the user and email provided. (format "Name <email@example.com>") |
--api-url |
URL to use when making API requests [default: "https://api.github.com"] |
--graphql-url |
URL to use when making GraphQL requests [default: "https://api.github.com"] |
release-please github-release --repo-url=googleapis/nodejs-firestore \
--token=$GITHUB_TOKEN
option | description |
---|---|
--package-name |
is the name of the package to publish to publish to an upstream registry such as npm. |
--repo-url |
is the URL of the repository on GitHub. |
--token |
a token with write access to --repo-url . |
--path |
create a release from a path other than the repository's root |
--api-url |
URL to use when making API requests [default: "https://api.github.com"] |
--graphql-url |
URL to use when making GraphQL requests [default: "https://api.github.com"] |
There is a probot application available, which allows you to deploy Release Please as a GitHub App:
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-8
: install client libraries from this dist-tag for versions
compatible with Node.js 8.This library follows Semantic Versioning.
Contributions welcome! See the Contributing Guide.
Please note that this README.md
, the samples/README.md
,
and a variety of configuration files in this repository (including .nycrc
and tsconfig.json
)
are generated from a central template. To edit one of these files, make an edit
to its template in this
directory.
Apache Version 2.0
See LICENSE
© 2010 - cnpmjs.org x YWFE | Home | YWFE