Standard Version

A utility for versioning using semver and CHANGELOG generation powered by Conventional Commits.

Having problems? Want to contribute? Join us on the node-tooling community Slack.

How It Works:

1. Follow the Conventional Commits Specification in your repository.
2. When you're ready to release, run

   standard-version

   .

standard-version

1. Retrieve the current version of your repository by looking at

   packageFiles

   [1], falling back to the last

   git tag

   .

2. bump

   the version in

   bumpFiles

   [1] based on your commits.
3. Generates a

   changelog

   based on your commits (uses conventional-changelog under the hood).
4. Creates a new

   commit

   including your

   bumpFiles

   [1] and updated CHANGELOG.
5. Creates a new

   tag

   with the new version number.

bumpFiles

,

packageFiles

and

updaters

standard-version

• packageFiles

  – User-defined files where versions can be read from and be "bumped".
  • Examples:

    package.json

    ,

    manifest.json

  • In most cases (including the default),

    packageFiles

    are a subset of

    bumpFiles

    .

• bumpFiles

  – User-defined files where versions should be "bumped", but not explicitly read from.
  • Examples:

    package-lock.json

    ,

    npm-shrinkwrap.json

• updaters

  – Simple modules used for reading

  packageFiles

  and writing to

  bumpFiles

  .

By default,

standard-version

That said, if you find your self asking How can I use standard-version for additional metadata files, languages or version files? – these configuration options will help!

Installing

standard-version

As a local

npm run

script

Install and add to

devDependencies

npm i --save-dev standard-version

Add an

npm run

package.json

{
  "scripts": {
    "release": "standard-version"
  }
}

Now you can use

npm run release

npm version

This has the benefit of making your repo/package more portable, so that other developers can cut releases without having to globally install

standard-version

As global

bin

Install globally (add to your

PATH

npm i -g standard-version

Now you can use

standard-version

npm version

This has the benefit of allowing you to use

standard-version

Using

npx

As of

[email protected]

npx

npm

npx

standard-version

package.json

npx standard-version

This method is especially useful when using

standard-version

Configuration

You can configure

standard-version

1. Placing a

   standard-version

   stanza in your

   package.json

   (assuming your project is JavaScript).
2. Creating a

   .versionrc

   ,

   .versionrc.json

   or

   .versionrc.js

   .
   • If you are using a

     .versionrc.js

     your default export must be a configuration object, or a function returning a configuration object.

Any of the command line parameters accepted by

standard-version

Customizing CHANGELOG Generation

By default (as of

6.0.0

standard-version

This preset:

• Adheres closely to the conventionalcommits.org specification.
• Is highly configurable, following the configuration specification maintained here.
  • We've documented these config settings as a recommendation to other tooling makers.

There are a variety of dials and knobs you can turn related to CHANGELOG generation.

As an example, suppose you're using GitLab, rather than GitHub, you might modify the following variables:

• commitUrlFormat

  : the URL format of commit SHAs detected in commit messages.

• compareUrlFormat

  : the URL format used to compare two tags.

• issueUrlFormat

  : the URL format used to link to issues.

Making these URLs match GitLab's format, rather than GitHub's.

CLI Usage

NOTE: To pass nested configurations to the CLI without defining them in the

package.json

use dot notation as the parameters

e.g. --skip.changelog

.

First Release

To generate your changelog for your first release, simply do:

# npm run script
npm run release -- --first-release
# global bin
standard-version --first-release
# npx
npx standard-version --first-release

This will tag a release without bumping the version

bumpFiles

When you are ready, push the git tag and

npm publish

Cutting Releases

If you typically use

npm version

# npm run script
npm run release
# or global bin
standard-version

As long as your git commit messages are conventional and accurate, you no longer need to specify the semver type - and you get CHANGELOG generation for free! \o/

After you cut a release, you can push the new git tag and

npm publish

npm publish --tag next

Release as a Pre-Release

Use the flag

--prerelease

Suppose the last version of your code is

1.0.0

# npm run script
npm run release -- --prerelease

This will tag your version as:

1.0.1-0

If you want to name the pre-release, you specify the name via

--prerelease 

For example, suppose your pre-release should contain the

alpha

# npm run script
npm run release -- --prerelease alpha

This will tag the version as:

1.0.1-alpha.0

Release as a Target Type Imperatively (

npm version

-like)

To forgo the automated version bump use

--release-as

major

minor

patch

Suppose the last version of your code is

1.0.0

fix:

minor

# npm run script
npm run release -- --release-as minor
# Or
npm run release -- --release-as 1.1.0

You will get version

1.1.0

1.0.1

NOTE: you can combine

--release-as

and

--prerelease

to generate a release. This is useful when publishing experimental feature(s).

Prevent Git Hooks

If you use git hooks, like pre-commit, to test your code before committing, you can prevent hooks from being verified during the commit step by passing the

--no-verify

# npm run script
npm run release -- --no-verify
# or global bin
standard-version --no-verify

Signing Commits and Tags

If you have your GPG key set up, add the

--sign

-s

standard-version

Lifecycle Scripts

standard-version

• prerelease

  : executed before anything happens. If the

  prerelease

  script returns a non-zero exit code, versioning will be aborted, but it has no other effect on the process.

• prebump

  /

  postbump

  : executed before and after the version is bumped. If the

  prebump

  script returns a version #, it will be used rather than the version calculated by

  standard-version

  .

• prechangelog

  /

  postchangelog

  : executes before and after the CHANGELOG is generated.

• precommit

  /

  postcommit

  : called before and after the commit step.

• pretag

  /

  posttag

  : called before and after the tagging step.

Simply add the following to your package.json to configure lifecycle scripts:

{
  "standard-version": {
    "scripts": {
      "prebump": "echo 9.9.9"
    }
  }
}

As an example to change from using GitHub to track your items to using your projects Jira use a

postchangelog

myproject

json
{
  "standard-version": {
    "scripts": {
      "postchangelog": "replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md"
    }
  }
}

Skipping Lifecycle Steps

You can skip any of the lifecycle steps (

bump

changelog

commit

tag

{
  "standard-version": {
    "skip": {
      "changelog": true
    }
  }
}

Committing Generated Artifacts in the Release Commit

If you want to commit generated artifacts in the release commit, you can use the

--commit-all

-a

release

{
  "standard-version": {
    "scripts": {
      "prerelease": "webpack -p --bail && git add "
    }
  }
}

{
  "scripts": {
    "release": "standard-version -a"
  }
}

Dry Run Mode

running

standard-version

--dry-run

# npm run script
npm run release -- --dry-run
# or global bin
standard-version --dry-run

Prefix Tags

Tags are prefixed with

v

-t

standard-version -t @scope/package\@

This will prefix your tags to look something like

@scope/[email protected]

If you do not want to have any tag prefix you can use the

-t

Note: simply -t or --tag-prefix without any value will fallback to the default 'v'

CLI Help

# npm run script
npm run release -- --help
# or global bin
standard-version --help

Code Usage

const standardVersion = require('standard-version')

// Options are the same as command line, except camelCase
// standardVersion returns a Promise
standardVersion({
  noVerify: true,
  infile: 'docs/CHANGELOG.md',
  silent: true
}).then(() => {
  // standard-version is done
}).catch(err => {
    console.error(standard-version failed with message: ${err.message})
})

TIP: Use the

silent

standard-version

console

FAQ

How is

standard-version

different from

semantic-release

?

semantic-release

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.

While both are based on the same foundation of structured commit messages,

standard-version

standard-version

standard-version

We think they are both fantastic tools, and we encourage folks to use

semantic-release

standard-version

Should I always squash commits when merging PRs?

The instructions to squash commits when merging pull requests assumes that one PR equals, at most, one feature or fix.

If you have multiple features or fixes landing in a single PR and each commit uses a structured message, then you can do a standard merge when accepting the PR. This will preserve the commit history from your branch after the merge.

Although this will allow each commit to be included as separate entries in your CHANGELOG, the entries will not be able to reference the PR that pulled the changes in because the preserved commit messages do not include the PR number.

For this reason, we recommend keeping the scope of each PR to one general feature or fix. In practice, this allows you to use unstructured commit messages when committing each little change and then squash them into a single commit with a structured message (referencing the PR number) once they have been reviewed and accepted.

Can I use

standard-version

for additional metadata files, languages or version files?

As of version

7.1.0

bumpFiles

packageFiles

1. Specify a custom

   bumpFile

   "

   filename

   ", this is the path to the file you want to "bump"
2. Specify the

   bumpFile

   "

   updater

   ", this is how the file will be bumped. a. If you're using a common type, you can use one of

   standard-version

   's built-in

   updaters

   by specifying a

   type

   . b. If your using an less-common version file, you can create your own

   updater

   .

// .versionrc
{
  "bumpFiles": [
    {
      "filename": "MY_VERSION_TRACKER.txt",
      // The `plain-text` updater assumes the file contents represents the version.
      "type": "plain-text"
    },
    {
      "filename": "a/deep/package/dot/json/file/package.json",
      // The `json` updater assumes the version is available under a `version` key in the provided JSON document.
      "type": "json"
    },
    {
      "filename": "VERSION_TRACKER.json",
      //  See "Custom `updater`s" for more details.
      "updater": "standard-version-updater.js"
    }
  ]
}

If using

.versionrc.js

updater

// .versionrc.js
const tracker = {
  filename: 'VERSION_TRACKER.json',
  updater: require('./path/to/custom-version-updater')
}

module.exports = {
  bumpFiles: [tracker],
  packageFiles: [tracker]
}

Custom

updater

s

An

updater

readVersion

writeVersion

readVersion(contents = string): string

This method is used to read the version from the provided file contents.

The return value is expected to be a semantic version string.

writeVersion(contents = string, version: string): string

This method is used to write the version to the provided contents.

The return value will be written directly (overwrite) to the provided file.

Let's assume our

VERSION_TRACKER.json

{
  "tracker": {
    "package": {
      "version": "1.0.0"
    }
  }
}

An acceptable

standard-version-updater.js

// standard-version-updater.js
const stringifyPackage = require('stringify-package')
const detectIndent = require('detect-indent')
const detectNewline = require('detect-newline')

module.exports.readVersion = function (contents) {
  return JSON.parse(contents).tracker.package.version;
}
module.exports.writeVersion = function (contents, version) {
  const json = JSON.parse(contents)
  let indent = detectIndent(contents).indent
  let newline = detectNewline(contents)
  json.tracker.package.version = version
  return stringifyPackage(json, indent, newline)
}

License

ISC