Project Icon

standard-version

版本管理和变更日志自动化工具

standard-version是一款基于语义化版本和约定式提交的自动化工具,用于管理版本号和生成变更日志。它可以自动分析提交历史、更新版本、生成变更记录并创建相应的Git提交和标签。尽管已停止维护,但对于特定场景下的项目管理仍有一定价值。

Standard Version

standard-version is deprecated. If you're a GitHub user, I recommend release-please as an alternative. If you're unable to use GitHub Actions, or if you need to stick with standard-version for some other reason, you can use the commit-and-tag-version fork of standard-version.

A utility for versioning using semver and CHANGELOG generation powered by Conventional Commits.

ci NPM version codecov Conventional Commits Community slack

Having problems? Want to contribute? Join us on the node-tooling community Slack.

How It Works:

  1. Follow the Conventional Commits Specification in your repository.
  2. When you're ready to release, run standard-version.

standard-version will then do the following:

  1. Retrieve the current version of your repository by looking at packageFiles[1], falling back to the last git tag.
  2. bump the version in bumpFiles[1] based on your commits.
  3. Generates a changelog based on your commits (uses conventional-changelog under the hood).
  4. Creates a new commit including your bumpFiles[1] and updated CHANGELOG.
  5. Creates a new tag with the new version number.

bumpFiles, packageFiles and updaters

standard-version uses a few key concepts for handling version bumping in your project.

  • packageFiles – User-defined files where versions can be read from and be "bumped".
    • Examples: package.json, manifest.json
    • In most cases (including the default), packageFiles are a subset of bumpFiles.
  • bumpFiles – User-defined files where versions should be "bumped", but not explicitly read from.
    • Examples: package-lock.json, npm-shrinkwrap.json
  • updaters – Simple modules used for reading packageFiles and writing to bumpFiles.

By default, standard-version assumes 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!

Installing standard-version

As a local 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.

Using npx

As of npm@5.2.0, npx is installed alongside npm. Using npx you can use standard-version without having to keep a package.json file by running: npx standard-version.

This method is especially useful when using standard-version in non-JavaScript projects.

Configuration

You can configure standard-version either by:

  1. Placing a standard-version stanza in your package.json (assuming your project is JavaScript).
  2. Creating a .versionrc, .versionrc.json or .versionrc.js.
  • If you are using a .versionrc.js your default export must be a configuration object, or a function returning a configuration object.

Any of the command line parameters accepted by standard-version can instead be provided via configuration. Please refer to the conventional-changelog-config-spec for details on available configuration options.

Customizing CHANGELOG Generation

By default (as of 6.0.0), standard-version uses the conventionalcommits preset.

This preset:

  • Adheres closely to the conventionalcommits.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 the package.json use dot notation as the parameters e.g. --skip.changelog.

First Release

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 publish your first release. \o/

Cutting Releases

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

This will tag your version as: 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 as: 1.0.1-alpha.0

Release as a Target Type Imperatively (npm version-like)

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 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.0 rather than what would be 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:

  • prerelease: executed before anything happens. If the prerelease script 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 prebump script 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 postchangelog script to replace the url fragment containing 'https://github.com/`myproject`/issues/' with a link to your Jira - assuming you have already installed replace

{
  "standard-version": {
    "scripts": {
      "postchangelog": "replace 'https://github.com/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, 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:

{
  "standard-version": {
    "scripts": {
      "prerelease": "webpack -p --bail && git add <file(s) to commit>"
    }
  }
}
{
  "scripts": {
    "release": "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

Prefix Tags

Tags are prefixed with v by default. If you would like to prefix your tags with something else, you can do so with the -t flag.

standard-version -t @scope/package\@

This will prefix your tags to look something like @scope/package@2.0.0

If you do not want to have any tag prefix you can use the -t flag and provide it with an empty string as value.

Note: simply -t or --tag-prefix without any value will fallback to the default 'v'

CLI Help

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

Code Usage

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 silent option to prevent standard-version from printing to the console.

FAQ

How is standard-version different from semantic-release?

semantic-release is 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-version takes 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-version only 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-release instead of standard-version if 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 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.

Can I use standard-version for additional metadata files, languages or version files?

As of version 7.1.0 you can configure multiple bumpFiles and packageFiles.

  1. Specify a custom bumpFile "filename", this is the path to the file you want to "bump"
  2. Specify the 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 updaters by 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.js as your configuration file, the updater may 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]
}

Custom updaters

An updater is expected to be a Javascript module with atleast two methods exposed: readVersion and 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.json has the following contents:

{
  "tracker": {
    "package": {
      "version": "1.0.0"
    }
  }
}

An acceptable

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

问小白

问小白是一个基于 DeepSeek R1 模型的智能对话平台,专为用户提供高效、贴心的对话体验。实时在线,支持深度思考和联网搜索。免费不限次数,帮用户写作、创作、分析和规划,各种任务随时完成!

Project Cover

白日梦AI

白日梦AI提供专注于AI视频生成的多样化功能,包括文生视频、动态画面和形象生成等,帮助用户快速上手,创造专业级内容。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

讯飞绘镜

讯飞绘镜是一个支持从创意到完整视频创作的智能平台,用户可以快速生成视频素材并创作独特的音乐视频和故事。平台提供多样化的主题和精选作品,帮助用户探索创意灵感。

Project Cover

讯飞文书

讯飞文书依托讯飞星火大模型,为文书写作者提供从素材筹备到稿件撰写及审稿的全程支持。通过录音智记和以稿写稿等功能,满足事务性工作的高频需求,帮助撰稿人节省精力,提高效率,优化工作与生活。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

Trae

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号