:trophy: Automate versioning and CHANGELOG generation, with semver.org and conventionalcommits.org
A utility for versioning using semver and CHANGELOG generation powered by Conventional Commits.
Having problems? Want to contribute? Join us on the node-tooling community Slack.
How It Works:
standard-version.
standard-versionwill then do the following:
packageFiles[1], falling back to the last
git tag.
bumpthe version in
bumpFiles[1] based on your commits.
changelogbased on your commits (uses conventional-changelog under the hood).
commitincluding your
bumpFiles[1] and updated CHANGELOG.
tagwith the new version number.
bumpFiles,
packageFilesand
updaters
standard-versionuses a few key concepts for handling version bumping in your project.
packageFiles– User-defined files where versions can be read from and be "bumped".
package.json,
manifest.json
packageFilesare a subset of
bumpFiles.
bumpFiles– User-defined files where versions should be "bumped", but not explicitly read from.
package-lock.json,
npm-shrinkwrap.json
updaters– Simple modules used for reading
packageFilesand writing to
bumpFiles.
By default,
standard-versionassumes 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 asking How can I use standard-version for additional metadata files, languages or version files? – these configuration options will help!
standard-version
npm runscript
Install and add to
devDependencies:
npm i --save-dev standard-version
npm runscript to your
package.json:
{ "scripts": { "release": "standard-version" } }
Now you can use
npm run releasein 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-versionon their machine.
bin
Install globally (add to your
PATH):
npm i -g standard-version
Now you can use
standard-versionin place of
npm version.
This has the benefit of allowing you to use
standard-versionon any repo/package without adding a dev dependency to each one.
npx
As of
[email protected],
npxis installed alongside
npm. Using
npxyou can use
standard-versionwithout having to keep a
package.jsonfile by running:
npx standard-version.
This method is especially useful when using
standard-versionin non-JavaScript projects.
You can configure
standard-versioneither by:
standard-versionstanza in your
package.json(assuming your project is JavaScript).
.versionrc,
.versionrc.jsonor
.versionrc.js.
.versionrc.jsyour default export must be a configuration object, or a function returning a configuration object.
Any of the command line parameters accepted by
standard-versioncan instead be provided via configuration. Please refer to the conventional-changelog-config-spec for details on available configuration options.
By default (as of
6.0.0),
standard-versionuses the conventionalcommits preset.
This preset:
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 the
package.jsonuse dot notation as the parameterse.g. --skip.changelog.
To generate your changelog for your first release, simply do:
# npm run script npm run release -- --first-release # global bin standard-version --first-release # npx npx standard-version --first-release
This will tag a release without bumping the version
bumpFiles1.
When you are ready, push the git tag and
npm publishyour first release. \o/
If you typically use
npm 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 and
npm publish(or
npm publish --tag next) when you're ready.
Use the flag
--prereleaseto 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
This will tag your version as:
1.0.1-0.
If you want to name the pre-release, you specify the name via
--prerelease.
For example, suppose your pre-release should contain the
alphaprefix:
# npm run script npm run release -- --prerelease alpha
This will tag the version as:
1.0.1-alpha.0
npm version-like)
To forgo the automated version bump use
--release-aswith the argument
major,
minoror
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 run the following:
# npm run script npm run release -- --release-as minor # Or npm run release -- --release-as 1.1.0
You will get version
1.1.0rather than what would be 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).
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
If you have your GPG key set up, add the
--signor
-sflag to your
standard-versioncommand.
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 the
prereleasescript 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 the
prebumpscript returns a version #, it will be used rather than the version calculated by
standard-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.com/
myproject/issues/' with a link to your Jira - assuming you have already installed replace
json { "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-allor
-aflag. You will need to stage the artifacts you want to commit, so your
releasecommand could look like this:
{ "standard-version": { "scripts": { "prerelease": "webpack -p --bail && git add " } } }
{ "scripts": { "release": "standard-version -a" } }
running
standard-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
Tags are prefixed with
vby 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 and provide it with an empty string as value.
Note: simply -t or --tag-prefix without any value will fallback to the default 'v'
# npm run script npm run release -- --help # or global bin standard-version --help
const standardVersion = 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}
) })
TIP: Use the
silentoption to prevent
standard-versionfrom printing to the
console.
standard-versiondifferent from
semantic-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 you without automatic pushing (to GitHub) or publishing (to an npm registry). Use of
standard-versiononly affects your local git repo - it doesn't affect remote resources at all. After you run
standard-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 use
semantic-releaseinstead of
standard-versionif it makes sense for their use-case.
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.
standard-versionfor additional metadata files, languages or version files?
As of version
7.1.0you can configure multiple
bumpFilesand
packageFiles.
bumpFile"
filename", this is the path to the file you want to "bump"
bumpFile"
updater", this is how the file will be bumped. a. If you're using a common type, you can use one of
standard-version's built-in
updatersby specifying a
type. b. If your using an less-common version file, you can create your own
updater.
// .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.jsas your configuration file, the
updatermay also be set as an object, rather than a path:
// .versionrc.js const tracker = { filename: 'VERSION_TRACKER.json', updater: require('./path/to/custom-version-updater') }module.exports = { bumpFiles: [tracker], packageFiles: [tracker] }
updaters
An
updateris expected to be a Javascript module with atleast two methods exposed:
readVersionand
writeVersion.
readVersion(contents = string): string
This method is used to read the version from the provided file contents.
The return value is expected to be a semantic version string.
writeVersion(contents = string, version: string): 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 our
VERSION_TRACKER.jsonhas the following contents:
{ "tracker": { "package": { "version": "1.0.0" } } }
An acceptable
standard-version-updater.jswould be:
// standard-version-updater.js const stringifyPackage = require('stringify-package') const detectIndent = require('detect-indent') const detectNewline = require('detect-newline')module.exports.readVersion = function (contents) { return JSON.parse(contents).tracker.package.version; }
module.exports.writeVersion = function (contents, version) { const json = JSON.parse(contents) let indent = detectIndent(contents).indent let newline = detectNewline(contents) json.tracker.package.version = version return stringifyPackage(json, indent, newline) }
ISC