Standard Version
stop using
npm version
, usestandard-version
it rocks!
Automatic versioning, CHANGELOG generation, and conventional commit messages.
Based on bk-conventional-changelog and bk-conventional-recommended-bump.
How it works
When you're ready to release to npm:
git checkout master; git pull origin master
- run
standard-version
git push --follow-tags origin; npm publish
standard-version
does the following:
- bumps the version in package.json/bower.json (based on your commit history)
- uses conventional-changelog to update CHANGELOG.md using SportHeroesGroup's preset
- commits package.json (et al.) and CHANGELOG.md
- tags a new release
Installation
As npm run
script
Install and add to devDependencies
:
npm i --save-dev standard-version
Add an npm run
script to your package.json:
{
"scripts": {
"release": "standard-version"
}
}
Now you can use npm run release
in place of 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
on their machine.
As global bin
Install globally (add to your PATH
):
npm i -g standard-version
Now you can use standard-version
in place of npm version
.
This has the benefit of allowing you to use standard-version
on any repo/package without adding a dev dependency to each one.
CLI Usage
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 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 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
(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 script
npm run release -- --prerelease
you will get version 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 the alpha
prefix:
# npm run script
npm run release -- --prerelease alpha
this will tag the version 1.0.1-alpha.0
Release as a target type imperatively like npm version
To forgo the automated version bump use --release-as
with the argument major
, minor
or patch
:
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 script
npm run release -- --release-as minor
# Or
npm run release -- --release-as 1.1.0
you will get version 1.1.0
rather than the auto generated version 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
option:
# 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
or -s
flag to your standard-version
command.
Lifecycle scripts
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:
-
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"
}
}
}
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-all
or -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
running 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 script
npm run release -- --dry-run
# or global bin
standard-version --dry-run
CLI Help
# npm run script
npm run release -- --help
# or global bin
standard-version --help
Code usage
Use the silent
option to stop standard-version
from printing anything
to the console.
var standardVersion = require('standard-version')
// Options are the same as command line, except camelCase
standardVersion({
noVerify: true,
infile: 'docs/CHANGELOG.md',
silent: true
}, function (err) {
if (err) {
console.error(`standard-version failed with message: ${err.message}`)
}
// standard-version is done
})
Commit Message Convention, at a Glance
patches:
git commit -a -m "✴️ [FIX] (parsing) fixed a bug in our parser"
features:
git commit -a -m "✅ [ADD] (parser) we now have a parser \o/"
breaking changes:
git commit -a -m "✅ [ADD] (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 "☑️ [DOC] fixed up the docs a bit"
git commit -a -m "🔄 [MOD] (controllers) Changed implementation"
git commit -a -m "🔀 [TEST] (services) Adjusted MemoryRange unit tests"
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)