release-please

What is release-please?

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.

What are release-please's main functionalities?

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();

Other packages similar to release-please

semantic-release

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

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

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.

README

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.

What's a Release PR?

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.

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:

• 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 types supported

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, and CHANGELOG.md
terraform-module	A terraform module, with a version in the README.md, and a CHANGELOG.md
simple	A repository with a version.txt and a CHANGELOG.md

Adding additional release types

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.

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:

1. If you haven't already done so, create a .github/workflows folder in your repository (this is where your actions will live).

2. Now create a .github/workflows/release-please.yml file with these contents:

    on:
      push:
        branches:
          - master
    name: release-please
    jobs:
      release-please:
        runs-on: ubuntu-latest
        steps:
          - uses: GoogleCloudPlatform/release-please-action@v1.3.0
            with:
              token: ${{ secrets.GITHUB_TOKEN }}
              release-type: node
              package-name: release-please-action
   

3. 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.

Automating publication to npm

With a few additions, the Release Please action can be made to publish to npm when a Release PR is merged:

on:
  push:
    branches:
      - master
name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: GoogleCloudPlatform/release-please-action@v1.3.0
        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 }}
      - 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.

Running as CLI

Install release-please globally:

npm i release-please -g

Creating/updating release PRs

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.

Creating a release on GitHub

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

Running as a GitHub App

There is a probot application available, which allows you to deploy Release Please as a GitHub App:

• github.com/googleapis/repo-automation-bots.

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 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 tags available

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

Versioning

This library follows Semantic Versioning.

Contributing

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.

License

Apache Version 2.0

See LICENSE