commit-and-tag-version

commit-and-tag-version is a fork of standard-version. Because of maintainer availability, standard-version was deprecated on 15th May 2022. The previous maintainer recommends release-please as an alternative for those who are using GitHub actions. This fork exists for those who can't switch to release-please, or who would like to continue using standard-version.

Can I simply swap the library to migrate? To migrate, you can drop in commit-and-tag-version in place of standard-version. There are no changes in 9.5.0, other than to add the package.json config key commit-and-tag-version (the previous configuration key standard-version will still work). 10.x drops support for deprecated node versions, 11.x is a formatting change if you're relying on the exact markdown format in the changelog, and 12.x drops support for node 14/16.

Why was it renamed commit-and-tag-version?. I didn't want to scope the package or name it standard-version-fork, and it was a good opportunity to make the purpose of the tool clearer. I also wanted to distinguish it from the other tool in this organisation, absolute-version, which just prints version information for pre-releases.

- [How It Works:](#how-it-works)
- [`bumpFiles`, `packageFiles` and `updaters`](#bumpfiles-packagefiles-and-updaters)
- [Maven Support (Java/Kotlin)](#maven-support-javakotlin)
- [Gradle Support (Java/Kotlin)](#gradle-support-javakotlin)
- [.NET Support](#net-support)

- [As a local `npm run` script](#as-a-local-npm-run-script)
- [As global `bin`](#as-global-bin)
- [Using `npx`](#using-npx)

- [Customizing CHANGELOG Generation](#customizing-changelog-generation)
- [Deeper customization](#deeper-customization)

- [First Release](#first-release)
- [Cutting Releases](#cutting-releases)
- [Release as a Pre-Release](#release-as-a-pre-release)
- [Release as a Target Type Imperatively (`npm version`-like)](#release-as-a-target-type-imperatively-npm-version-like)
- [Prevent Git Hooks](#prevent-git-hooks)
- [Signing Commits and Tags](#signing-commits-and-tags)
- [Lifecycle Scripts](#lifecycle-scripts)
- [Skipping Lifecycle Steps](#skipping-lifecycle-steps)
- [Committing Generated Artifacts in the Release Commit](#committing-generated-artifacts-in-the-release-commit)
- [Dry Run Mode](#dry-run-mode)
- [Prefix Tags](#prefix-tags)
- [Tag replacement](#tag-replacement)
- [Generate changelogs for old releases](#generate-changelogs-for-old-releases)
- [CLI Help](#cli-help)

- [How is `commit-and-tag-version` different from `semantic-release`?](#how-is-commit-and-tag-version-different-from-semantic-release)
- [Should I always squash commits when merging PRs?](#should-i-always-squash-commits-when-merging-prs)
- [Can I use `commit-and-tag-version` for additional metadata files, languages or version files?](#can-i-use-commit-and-tag-version-for-additional-metadata-files-languages-or-version-files)
  - [Custom `updater`s](#custom-updaters)
    - [`readVersion(contents = string): string`](#readversioncontents--string-string)
    - [`writeVersion(contents = string, version: string): string`](#writeversioncontents--string-version-string-string)

How It Works

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

1. Retrieve the current version of your repository by looking at packageFiles1, falling back to the last git tag.
2. bump the version in bumpFiles1 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 bumpFiles1 and updated CHANGELOG.
5. Creates a new tag with the new version number.

bumpFiles, packageFiles and updaters

• packageFiles – User-defined files where versions can be read from and be "bumped".

• bumpFiles – User-defined files where versions should be "bumped", but not explicitly read from.

• updaters – Simple modules used for reading packageFiles and writing to bumpFiles.

Maven Support (Java/Kotlin)

commit-and-tag-version --packageFiles pom.xml --bumpFiles pom.xml

Gradle Support (Java/Kotlin)

commit-and-tag-version --packageFiles build.gradle --bumpFiles build.gradle

.NET Support

commit-and-tag-version --packageFiles <YOUR-PROJECT-NAME>.csproj --bumpFiles <YOUR-PROJECT-NAME>.csproj

YAML Support

commit-and-tag-version --packageFiles file.yaml --bumpFiles file.yaml

Installing commit-and-tag-version

As a local npm run script

npm i --save-dev commit-and-tag-version

{
  "scripts": {
    "release": "commit-and-tag-version"
  }
}

As global bin

npm i -g commit-and-tag-version

Using npx

Configuration

1. Placing a commit-and-tag-version stanza in your package.json (assuming

your project is JavaScript).

> Note for users who have migrated to
`commit-and-tag-version` from `standard-version`: the previous package.json configuration key of `standard-version` will still work.

1. 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.

Customizing CHANGELOG Generation

• 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.

Deeper customization

{
  "commit-and-tag-version": {
    "writerOpts": {
      "commitsSort": false
    }
  }
}

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

# npm run script
npm run release -- --first-release
# global bin
commit-and-tag-version --first-release
# npx
npx commit-and-tag-version --first-release

# npm run script
npm run release
# or global bin
commit-and-tag-version

# npm run script
npm run release -- --prerelease

# npm run script
npm run release -- --prerelease alpha

# npm run script
npm run release -- --release-as minor
# Or
npm run release -- --release-as 1.1.0

# npm run script
npm run release -- --no-verify
# or global bin
commit-and-tag-version --no-verify

{
  "commit-and-tag-version": {
    "scripts": {
      "prebump": "echo 9.9.9"
    }
  }
}

{
  "commit-and-tag-version": {
    "scripts": {
      "postchangelog": "replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md"
    }
  }
}

Skipping Lifecycle Steps

{
  "commit-and-tag-version": {
    "skip": {
      "changelog": true
    }
  }
}

Committing Generated Artifacts in the Release Commit

{
  "commit-and-tag-version": {
    "scripts": {
      "prerelease": "webpack -p --bail && git add <file(s) to commit>"
    }
  }
}

{
  "scripts": {
    "release": "commit-and-tag-version -a"
  }
}

Dry Run Mode

# npm run script
npm run release -- --dry-run
# or global bin
commit-and-tag-version --dry-run

Prefix Tags

commit-and-tag-version -t @scope/package\@

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

Tag replacement

Generate changelogs for old releases

//.versionrc
{
  "releaseCount": 0
}

//package.json

"commit-and-tag-version": {
  "releaseCount": 0
}

CLI Help

# npm run script
npm run release -- --help
# or global bin
commit-and-tag-version --help

Code Usage

const commitAndTagVersion = require("commit-and-tag-version");

// Options are the same as command line, except camelCase
// commitAndTagVersion returns a Promise
commitAndTagVersion({
  noVerify: true,
  infile: "docs/CHANGELOG.md",
  silent: true,
})
  .then(() => {
    // commit-and-tag-version is done
  })
  .catch((err) => {
    console.error(`commit-and-tag-version failed with message: ${err.message}`);
  });

FAQ

How is commit-and-tag-version different from semantic-release?

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.

Should I always squash commits when merging PRs?

Can I use commit-and-tag-version for additional metadata files, languages or version files?

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 `commit-and-tag-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": "commit-and-tag-version-updater.js"
    }
  ]
}

// .versionrc.js
const tracker = {
  filename: "VERSION_TRACKER.json",
  updater: require("./path/to/custom-version-updater"),
};

module.exports = {
  bumpFiles: [tracker],
  packageFiles: [tracker],
};

Custom updaters

readVersion(contents = string): string

writeVersion(contents = string, version: string): string

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

// commit-and-tag-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);
};

Why do breaking changes before 1.0.0 not trigger a 1.0.0 release?

1017b00 chore: initial commit
9e2ba95 (tag: v0.0.2) chore(release): 0.0.2
3598012 fix!: Example breaking change
1a4994a (tag: v0.1.0) chore(release): 0.1.0

License