standard-version6.0.1 • Public • Published
Having problems? want to contribute? join our community slack.
how it works:
- when you land commits on your
masterbranch, select the Squash and Merge option.
- add a title and body that follows the Conventional Commits Specification.
- when you're ready to release:
git checkout master; git pull origin master
git push --follow-tags origin master && npm publish(or,
gem push, etc.)
standard-version does the following:
- bumps the version in metadata files (package.json, composer.json, etc).
- uses conventional-changelog to update CHANGELOG.md
- commits package.json (et al.) and CHANGELOG.md
- tags a new release
npm run script
Install and add to
npm i --save-dev standard-version
npm run script to your package.json:
Now you can use
npm run release in place of
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 on their machine.
As global bin
Install globally (add to your
npm i -g standard-version
Now you can use
standard-version in place of
This has the benefit of allowing you to use
standard-version on any repo/package without adding a dev dependency to each one.
You can configure
standard-version either by:
- Placing a
standard-versionstanza in your
- Creating a
Any of the command line paramters accepted by
standard-version can instead
be provided via configuration.
Customizing CHANGELOG Generation
standard-version uses the conventionalcommits preset.
- adheres closely to the conventionalcommits.org specification.
- is highly configurable, following the configuration specification
- 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.
To generate your changelog for your first release, simply do:
# npm run scriptnpm run release -- --first-release# or global binstandard-version --first-release
This will tag a release without bumping the version in package.json (et al.).
When ready, push the git tag and
npm publish your first release. \o/
Cut a Release
If you typically use
npm 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 and
npm publish (or
npm publish --tag next) when you're ready.
Release as a pre-release
Use the flag
--prerelease to generate pre-releases:
Suppose the last version of your code is
1.0.0, and your code to be committed has patched changes. Run:
# npm run scriptnpm run release -- --prerelease
you will get version
If you want to name the pre-release, you specify the name via
For example, suppose your pre-release should contain the
# npm run scriptnpm run release -- --prerelease alpha
this will tag the version
Release as a target type imperatively like
To forgo the automated version bump use
--release-as with the argument
Suppose the last version of your code is
1.0.0, you've only landed
fix: commits, but
you would like your next release to be a
minor. Simply do:
# npm run scriptnpm run release -- --release-as minor# Ornpm run release -- --release-as 1.1.0
you will get version
1.1.0 rather than the auto generated version
NOTE: you can combine
--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
# npm run scriptnpm run release -- --no-verify# or global binstandard-version --no-verify
Signing commits and tags
If you have your GPG key set up, add the
-s flag to your
standard-version supports 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 the
prereleasescript returns a non-zero exit code, versioning will be aborted, but it has no other effect on the process.
postbump: executed before and after the version is bumped. If the
prebumpscript returns a version #, it will be used rather than the version calculated by
postchangelog: executes before and after the CHANGELOG is generated.
postcommit: called before and after the commit step.
posttag: called before and after the tagging step.
Simply add the following to your package.json to configure lifecycle scripts:
As an example to change from using GitHub to track your items to using your projects Jira use a
postchangelog script to replace the url fragment containing 'https://github.com/
with a link to your Jira - assuming you have already installed replace
Skipping lifecycle steps
You can skip any of the lifecycle steps (
by adding the following to your package.json:
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
-a flag. You will need to stage the artifacts you want to commit, so your
release command could look like this:
"prerelease": "webpack -p --bail","release": "git add <file(s) to commit> && standard-version -a"
Dry run mode
standard-version with the flag
--dry-run allows you to see what
commands 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 with
v by default. If you would like to prefix your tags with something else, you can do so with the
standard-version -t @scope/package\@
This will prefix your tags to look something like
If you do not want to have any tag prefix you can use the
-t flag without value.
# npm run scriptnpm run release -- --help# or global binstandard-version --help
silent option to stop
standard-version from printing anything
to the console.
const standardVersion =// Options are the same as command line, except camelCase// standardVersion returns a Promise
Commit Message Convention, at a Glance
git commit -a -m "fix(parsing): fixed a bug in our parser"
git commit -a -m "feat(parser): we now have a parser \o/"
git commit -a -m "feat(new-parser): introduces a new parsing libraryBREAKING CHANGE: new library does not support foo-construct"
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.
Tell your users that you adhere to the Conventional Commits specification:
standard-version different from
semantic-release is a fully automated library/system for versioning, changelog generation, git tagging, and publishing to the npm registry.
standard-version is different because it handles the versioning, changelog generation, and git tagging for you without automatic pushing (to GitHub) or publishing (to an npm registry). Use of
standard-version only affects your local git repo - it doesn't affect remote resources at all. After you run
standard-version, you still have the ability to review things and correct mistakes if you want to.
They are both based on the same foundation of structured commit messages (using Angular format), but
standard-version is a good choice for folks who are not yet comfortable letting publishes go out automatically. In this way, you can view
standard-version as an incremental step to adopting
We think they are both fantastic tools, and we encourage folks to use
semantic-release instead of
standard-version if it makes sense for them.
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.