sportheroesStandard Version
stop using
npm version, usestandard-versionit 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 master; 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-versionAdd 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-versionNow 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-releaseThis 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-versionAs 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 -- --prereleaseyou 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 alphathis 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.0you will get version 1.1.0 rather than the auto generated version 1.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-verify option:
# npm run script
npm run release -- --no-verify
# or global bin
standard-version --no-verifySigning 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 theprebumpscript 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-runCLI Help
# npm run script
npm run release -- --help
# or global bin
standard-version --helpCode 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:
[](https://conventionalcommits.org)