npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ftl-release-please

v11.14.2

Published

generate release PRs based on the conventionalcommits.org spec

Downloads

4

Readme

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.

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. 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 its lifecycle by the status label on the PR 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: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).

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.

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

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

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, 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 | | 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 |

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@v2
             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@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.

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. | | --pull-request-title-pattern | add title pattern to make release PR, defaults to using chore${scope}: release${component} ${version}. |

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:

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