release-please
Advanced tools
release-please is an automated release tool for GitHub repositories. It automates the process of generating release notes, creating GitHub releases, and versioning based on conventional commits. This helps maintainers streamline their release process and ensure consistency.
Automated Release Notes
This feature allows you to automatically generate release notes based on the commits in your repository. The code sample demonstrates how to create a GitHub release with release notes.
const { GitHubRelease } = require('release-please');
const githubRelease = new GitHubRelease({
repoUrl: 'https://github.com/owner/repo',
packageName: 'my-package',
token: 'your-github-token'
});
githubRelease.createRelease();Version Bumping
This feature automates the process of bumping the version of your package based on the commits. The code sample shows how to bump the version of your package.
const { Version } = require('release-please');
const version = new Version({
repoUrl: 'https://github.com/owner/repo',
packageName: 'my-package',
token: 'your-github-token'
});
version.bumpVersion();Changelog Generation
This feature generates a changelog file based on the commits in your repository. The code sample demonstrates how to generate a changelog.
const { Changelog } = require('release-please');
const changelog = new Changelog({
repoUrl: 'https://github.com/owner/repo',
packageName: 'my-package',
token: 'your-github-token'
});
changelog.generateChangelog();semantic-release automates the versioning and package publishing process based on the commit messages. It is highly configurable and integrates with various CI/CD pipelines. Compared to release-please, semantic-release offers more plugins and customization options.
standard-version is a tool for versioning and changelog generation based on conventional commits. It is simpler and more lightweight compared to release-please, making it suitable for smaller projects or those with simpler release requirements.
lerna is a tool for managing JavaScript projects with multiple packages. It can also handle versioning and changelog generation. While it offers more features for monorepos, it may be overkill for single-package repositories compared to 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.
It does not handle publication to package managers or handle complex branch management.
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 in 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: snapshot is a special state for snapshot version bumpsautorelease: 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.We highly recommend that you use squash-merges when merging pull requests. A linear git history makes it much easier to:
git bisect is helpful for tracking down which
change introduced a bugfeat: introduce feature A and then fix: some bugfix introduced in the first commit. The fix commit is actually irrelevant to the release
notes as there was never a bug experienced in the main branch.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:
:warning: Important: The additional messages must be added to the bottom of the commit.
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
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 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.
autorelease: pending or autorelease: triggered label in an old PRCheck 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.
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.
Release Please automates releases for the following flavors of repositories:
| release type | description |
|---|---|
dart | A repository with a pubspec.yaml and a CHANGELOG.md |
elixir | A repository with a mix.exs and a CHANGELOG.md |
go | A repository with a CHANGELOG.md |
helm | A repository with a Chart.yaml and a CHANGELOG.md |
java | A strategy that generates SNAPSHOT version after each release |
krm-blueprint | A kpt package, with 1 or more KRM files and a CHANGELOG.md |
maven | Strategy for Maven projects, generates SNAPSHOT version after each release and updates pom.xml automatically |
node | A Node.js repository, with a package.json and CHANGELOG.md |
expo | An Expo based React Native repository, with a package.json, app.json and CHANGELOG.md |
ocaml | An OCaml repository, containing 1 or more opam or esy files and a CHANGELOG.md |
php | A repository with a composer.json and a CHANGELOG.md |
python | A Python repository, with a setup.py, setup.cfg, CHANGELOG.md and optionally a pyproject.toml and a <project>/__init__.py |
ruby | A repository with a version.rb and a CHANGELOG.md |
rust | A 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 |
sfdx | A repository with a sfdx-project.json and a CHANGELOG.md |
simple | A repository with a version.txt and a CHANGELOG.md |
terraform-module | A terraform module, with a version in the README.md, and a CHANGELOG.md |
There are a variety of ways you can deploy release-please:
The easiest way to run Release Please is as a GitHub action. Please see google-github-actions/release-please-action for installation and configuration instructions.
Please see Running release-please CLI for all the configuration options.
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.
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.
Release Please provides several configuration options to allow customizing your release process. Please see customizing.md for more details.
Release Please also supports releasing multiple artifacts from the same repository. See more at manifest-releaser.md.
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.
For more information on the design of the library, see design.
For common issues and help troubleshooting your configuration, see Troubleshooting.
Apache Version 2.0
See LICENSE
FAQs
generate release PRs based on the conventionalcommits.org spec
The npm package release-please receives a total of 359,655 weekly downloads. As such, release-please popularity was classified as popular.
We found that release-please demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.