Standard Version

Having problems? want to contribute? join ourcommunity slack.

Automate versioning and CHANGELOG generation, withsemverand conventional commit messages.

how it works:

1. when you land commits on yourmasterbranch, select theSquash and Mergeoption.
2. add a title and body that follows theConventional Commits Specification.
3. when you're ready to release:
4. git checkout master; git pull origin master
5. runstandard-version
6. git push --follow-tags origin master && npm publish (or,docker push,gem push,etc.)

standard-versiondoes the following:

1. bumps the version in metadata files (package.json, composer.json, etc).
2. usesconventional-changelogto updateCHANGELOG.md
3. commitspackage.json (et al.)andCHANGELOG.md
4. tags a new release

Installation

Asnpm runscript

Install and add todevDependencies:

npm i --save-dev standard-version

Add annpm runscriptto yourpackage.json:

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

Now you can usenpm run releasein 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-versionon their machine.

As global bin

Install globally (add to yourPATH):

npm i -g standard-version

Now you can usestandard-versionin place ofnpm version.

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

Configuration

You can configurestandard-versioneither by:

1. Placing astandard-versionstanza in yourpackage.json(assuming your project is JavaScript).
2. Creating a.versionrc,.versionrc.jsonor.versionrc.js.

• If you are using a.versionrc.jsyour default export must be a configuration object, or a function returning a configuration object.

Any of the command line parameters accepted bystandard-versioncan instead be provided via configuration. Please refer to theconventional-changelog-config-specfor details on available configuration options.

Customizing CHANGELOG Generation

By default,standard-versionuses theconventionalcommits preset.

This preset:

• adheres closely to theconventionalcommits.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 thepackage.jsonuse dot notation as the parameterse.g. --skip.changelog.

First Release

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

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

This will tag a releasewithout bumping the version in package.json (et al.).

When ready, push the git tag andnpm publishyour first release. \o/

Cut a Release

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

#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 andnpm publish(ornpm publish --tag next) when you're ready.

Release as a pre-release

Use the flag--prereleaseto 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 script
npm run release -- --prerelease

you will get version1.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 theAlphaprefix:

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

this will tag the version1.0.1- Alpha.0

Release as a target type imperatively likenpm version

To forgo the automated version bump use--release-aswith the argumentmajor,minororpatch:

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

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

you will get version1.1.0rather than the auto generated version1.0.1.

NOTE:you can combine--release-asand--prereleaseto 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-verifyoption:

#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--signor-sflag to yourstandard-versioncommand.

Lifecycle scripts

standard-versionsupports lifecycle scripts. These allow you to execute your own supplementary commands during the release. The following hooks are available and execute in the order documented:

• prerelease:executed before anything happens. If theprereleasescript 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 theprebump script returns a version #, it will be used rather than the 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 a postchangelogscript to replace the url fragment containing 'https://github /`myproject`/issues/' with a link to your Jira - assuming you have already installedreplace

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

Skipping lifecycle steps

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

Committing generated artifacts in the release commit

If you want to commit generated artifacts in the release commit (e.g.#96), you can use the--commit-allor-aflag. You will need to stage the artifacts you want to commit, so yourreleasecommand could look like this:

"prerelease":"webpack -p --bail",
"release":"git add <file(s) to commit> && standard-version -a"

Dry run mode

runningstandard-versionwith the flag--dry-runallows you to see what commands would be run, without committing to git or updating files.

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

Prefix Tags

Tags are prefixed withvby default. If you would like to prefix your tags with something else, you can do so with the-tflag.

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-tflag without value.

CLI Help

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

Code usage

Use thesilentoption to stopstandard-versionfrom printing anything to the console.

conststandardVersion=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}`)
})

Commit Message Convention, at a Glance

patches:

git commit -a -m"fix(parsing): fixed a bug in our parser"

features:

git commit -a -m"feat(parser): we now have a parser \o/"

breaking changes:

git commit -a -m"feat(new-parser): introduces a new parsing library
BREAKING CHANGE: new library does not support foo-construct"

other changes:

You decide, e.g., docs, chore, etc.

git commit -a -m"docs: fixed up the docs a bit"

but wait, there's more!

Github usernames (@bcoe) and issue references (#133) will be swapped out for the appropriate URLs in your CHANGELOG.

Badges!

Tell your users that you adhere to the Conventional Commits specification:

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)

FAQ

How isstandard-versiondifferent fromsemantic-release?

semantic-releaseis 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-versiontakes a different approach by handling versioning, changelog generation, and git tagging for youwithoutautomatic pushing (to GitHub) or publishing (to an npm registry). Use ofstandard-versiononly 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-releaseinstead ofstandard-versionif it makes sense for their use-case.

Should I always squash commits when merging PRs?

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

License

ISC