Release

Release is a command line tool to automatically generate a new GitHub Release and populates it with the changes (commits) made since the last release.

Usage

Install the package directly from GitHub using either npm or pnpm:

npm install --global github:404mat/release
# or
pnpm add --global github:404mat/release

Once that's done, you can run this command inside your project's directory:

release

Running release without arguments starts an interactive prompt where you can choose the release type, whether to create an annotated tag only, and an update summary for tag-only releases. Choose "No version bump" to create a GitHub Release from the most recent commit and tag. The tag-only and summary questions appear after the commits have been classified and the changelog has been generated.

A <type> argument can still be passed for non-interactive use.

According to the SemVer spec, the argument can have one of these values:

• major: Incompatible API changes were introduced
• minor: Functionality was added in a backwards-compatible manner
• patch: Backwards-compatible bug fixes were applied

In addition to those values, we also support creating pre-releases like 3.0.0-canary.1:

release pre

You can also apply a custom suffix in place of "canary" like this:

release pre <suffix>

Assuming that you provide "beta" as the <suffix> your release will then be 3.0.0-beta.1 – and so on...

When creating a version bump, Release preserves the format of the latest release tag. For example, after v1.2.3, a patch bump creates v1.2.4. The version in package.json remains standard SemVer without the prefix. To prevent accidental releases, Release stops if the latest release tag and package.json have different versions.

Add --tag-only to a version bump to create and push an annotated Git tag containing the generated changelog, without creating a GitHub Release:

release patch --tag-only

Add --summary (or -S) to provide short update text separately from the generated changelog. For tag-only releases, the summary is stored as Update-Summary metadata in the annotated tag so a publishing workflow can include it in an application's update feed:

release patch --tag-only --summary "New categorization feature, improvements, and more"

Add --dry-run to preview the release that would be created without writing files, creating commits or tags, pushing, uploading to GitHub, or opening the browser:

release patch --dry-run

Dry runs still authenticate with GitHub and check repository/release state. Running release --dry-run without a type also uses the interactive prompts.

Options

The following command will show you a list of all available options:

release help

Pre-Defining Types

If you want to automate release even further, specify the change type of your commits by adding it to the title or description within parenthesis:

Error logging works now (patch)

Assuming that you've defined it for a certain commit, release won't ask you to set a type for it manually. This will make the process of creating a release even faster.

To pre-define that a commit should be excluded from the list, you can use this keyword:

This is a commit message (ignore)

Custom Hook

Sometimes you might want to filter the information that gets inserted into new releases by adding an intro text, replacing certain data or just changing the order of the changes.

With a custom hook, the examples above (and many more) are very easy to accomplish:

By default, release will look for a file named release.js in the root directory of your project. This file should export a function with two parameters and always return a String (the final release):

export default async (markdown, metaData) => {
  // Use the available data to create a custom release
  return markdown;
};

In the example above, markdown contains the release as a String (if you just want to replace something). In addition, metaData contains these properties:

Property Name	Content
changeTypes	The types of changes and their descriptions
commits	A list of commits since the latest release
groupedCommits	Similar to commits, but grouped by the change types
authors	The GitHub usernames of the release collaborators

Hint: You can specify a custom location for the hook file using the --hook or -H flag, which takes in a path relative to the current working directory.

Why?

Release makes it easy to generate GitHub Releases from the command line, without having to open a browser and manually prepare the release notes.

Contributing

The GitHub OAuth callback service is configured with the RELEASE_AUTH_URL environment variable. Set GITHUB_CLIENT_ID to the client ID for the OAuth application used by that service.

1. Fork this repository to your own GitHub account and then clone it to your local device
2. Uninstall the package if it's already installed: pnpm remove --global release
3. Link the package to the global module directory: pnpm link --global
4. You can now use release on the command line!

As always, you can use pnpm test to run the tests and see if your changes have broken anything.

Author

Leo Lamprecht (@leo)