Repository files navigation

standard-version is deprecated. If you're a GitHub user, I recommendrelease-please as an alternative. If you're unable to use GitHub Actions, or if you need to stick withstandard-version for some other reason, you can use thecommit-and-tag-version fork ofstandard-version.

A utility for versioning usingsemver and CHANGELOG generation powered byConventional Commits.

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

How It Works:

1. Follow theConventional Commits Specification in your repository.
2. When you're ready to release, runstandard-version.

standard-version will then do the following:

1. Retrieve the current version of your repository by looking atpackageFiles[1], falling back to the lastgit tag.
2. bump the version inbumpFiles[1] based on your commits.
3. Generates achangelog based on your commits (usesconventional-changelog under the hood).
4. Creates a newcommit including yourbumpFiles[1] and updated CHANGELOG.
5. Creates a newtag with the new version number.

standard-version uses a few key concepts for handling version bumping in your project.

• packageFiles – User-defined files where versions can be read fromand be "bumped".
  • Examples:package.json,manifest.json
  • In most cases (including the default),packageFiles are a subset ofbumpFiles.
• 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 readingpackageFiles and writing tobumpFiles.

By default,standard-version assumes you're working in a NodeJS based project... because of this, for the majority of projects you might never need to interact with these options.

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

Install and add todevDependencies:

npm i --save-dev standard-version

Add annpm run script to yourpackage.json:

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

Now you can usenpm run release in place ofnpm version.

This has the benefit of making your repo/package more portable, so that other developers can cut releases without having to globally installstandard-version on their machine.

Install globally (add to yourPATH):

npm i -g standard-version

Now you can usestandard-version in place ofnpm version.

This has the benefit of allowing you to usestandard-version on any repo/package without adding a dev dependency to each one.

As ofnpm@5.2.0,npx is installed alongsidenpm. Usingnpx you can usestandard-version without having to keep apackage.json file by running:npx standard-version.

This method is especially useful when usingstandard-version in non-JavaScript projects.

You can configurestandard-version either by:

1. Placing astandard-version stanza in yourpackage.json (assumingyour 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 bystandard-version can insteadbe provided via configuration. Please refer to theconventional-changelog-config-spec for details on available configuration options.

By default (as of6.0.0),standard-version uses theconventionalcommits preset.

This preset:

• Adheres closely to theconventionalcommits.orgspecification.
• Is highly configurable, following the configuration specificationmaintained 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.

NOTE: To pass nested configurations to the CLI without defining them in thepackage.json use dot notation as the parameterse.g. --skip.changelog.

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

# npm run scriptnpm run release -- --first-release# global binstandard-version --first-release# npxnpx standard-version --first-release

This will tag a releasewithout bumping the versionbumpFiles1.

When you are ready, push the git tag andnpm publish your first release. \o/

If you typically usenpm version to cut a new release, do this instead:

# npm run scriptnpm run release# or global binstandard-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 andnpm publish (ornpm publish --tag next) when you're ready.

Use the flag--prerelease to generate pre-releases:

Suppose the last version of your code is1.0.0, and your code to be committed has patched changes. Run:

# npm run scriptnpm 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 <name>.

For example, suppose your pre-release should contain thealpha prefix:

# npm run scriptnpm run release -- --prerelease alpha

This will tag the version as:1.0.1-alpha.0

To forgo the automated version bump use--release-as with the argumentmajor,minor orpatch.

Suppose the last version of your code is1.0.0, you've only landedfix: commits, butyou would like your next release to be aminor. Simply run the following:

# npm run scriptnpm run release -- --release-as minor# Ornpm run release -- --release-as 1.1.0

You will get version1.1.0 rather than what would be the auto-generated version1.0.1.

NOTE: you can combine--release-as and--prerelease to generate a release. This is useful when publishing experimental feature(s).

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 option:

# npm run scriptnpm run release -- --no-verify# or global binstandard-version --no-verify

If you have your GPG key set up, add the--sign or-s flag to yourstandard-version command.

standard-version supports lifecycle scripts. These allow you to execute yourown supplementary commands during the release. The followinghooks are available and execute in the order documented:

• prerelease: executed before anything happens. If theprerelease script returns anon-zero exit code, versioning will be aborted, but it has no other effect on theprocess.
• prebump/postbump: executed before and after the version is bumped. If theprebumpscript returns a version #, it will be used rather thanthe version calculated bystandard-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 apostchangelog script to replace the url fragment containing 'https://github.com/`myproject`/issues/'with a link to your Jira - assuming you have already installedreplace

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

You can skip any of the lifecycle steps (bump,changelog,commit,tag),by adding the following to your package.json:

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

If you want to commit generated artifacts in the release commit, you can use the--commit-all or-a flag. You will need to stage the artifacts you want to commit, so yourrelease command could look like this:

{"standard-version": {"scripts": {"prerelease":"webpack -p --bail && git add <file(s) to commit>"    }  }}

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

runningstandard-version with the flag--dry-run allows you to see whatcommands would be run, without committing to git or updating files.

# npm run scriptnpm run release -- --dry-run# or global binstandard-version --dry-run

Tags are prefixed withv by default. If you would like to prefix your tags with something else, you can do so with the-t flag.

standard-version -t @scope/package\@

This will prefix your tags to look something like@scope/package@2.0.0

If you do not want to have any tag prefix you can use the-t flag and provide it with anempty string as value.

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

# npm run scriptnpm run release -- --help# or global binstandard-version --help

conststandardVersion=require('standard-version')// Options are the same as command line, except camelCase// standardVersion returns a PromisestandardVersion({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 thesilent option to preventstandard-version from printing to theconsole.

semantic-release is described as:

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 takes a different approach by handling versioning, changelog generation, and git tagging for youwithout automatic pushing (to GitHub) or publishing (to an npm registry). Use ofstandard-version only affects your local git repo - it doesn't affect remote resources at all. After you runstandard-version, you can review your release state, correct mistakes and follow the release strategy that makes the most sense for your codebase.

We think they are both fantastic tools, and we encourage folks to usesemantic-release instead ofstandard-version if it makes sense for their use-case.

The instructions to squash commits when merging pull requests assumes thatone 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 willnot 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.

As of version7.1.0 you can configure multiplebumpFiles andpackageFiles.

1. Specify a custombumpFile "filename", this is the path to the file you want to "bump"
2. Specify thebumpFile "updater", this ishow the file will be bumped.a. If you're using a common type, you can use one ofstandard-version's built-inupdaters by specifying atype.b. If your using an less-common version file, you can create your ownupdater.

// .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 as your configuration file, theupdater may also be set as an object, rather than a path:

// .versionrc.jsconsttracker={filename:'VERSION_TRACKER.json',updater:require('./path/to/custom-version-updater')}module.exports={bumpFiles:[tracker],packageFiles:[tracker]}

Anupdater is expected to be a Javascript module withatleast two methods exposed:readVersion andwriteVersion.

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

The return value is expected to be a semantic version 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 ourVERSION_TRACKER.json has the following contents:

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

An acceptablestandard-version-updater.js would be:

// standard-version-updater.jsconststringifyPackage=require('stringify-package')constdetectIndent=require('detect-indent')constdetectNewline=require('detect-newline')module.exports.readVersion=function(contents){returnJSON.parse(contents).tracker.package.version;}module.exports.writeVersion=function(contents,version){constjson=JSON.parse(contents)letindent=detectIndent(contents).indentletnewline=detectNewline(contents)json.tracker.package.version=versionreturnstringifyPackage(json,indent,newline)}

ISC