@theo.gravity/version-bump

version-bump

Version bump package.json (or a file with a version property) via various version bump plugins/strategies.

What it offers

• Can update package.json or any file with a version property using semver rules.
• Use a custom config file with additional callback handlers.
• Plugin-based architecture - develop your own version bump strategies and offer it for use on the command line or as part of the API
• Built-in CLI bump strategy works like npm version (git support is a separate plugin)

Contents

• Bump rules
• Install
• Quick start usage
• CLI Usage
  • Get help on a version strategy
• Custom configuration file
  • Additional properties
    • async onBeforeRelease(versionData) : versionData
• Installing other strategies (plugins)
  • Available strategies (plugins)

Bump rules

These rules are not designed to work like the npm package semver or npm version.

• horizontal: Sample version
• vertical: bump level used
• value: new bumped version

	1.0.0	2.1.0	3.2.1	4.0.0-0	5.0.0+0	6.0.0-pre.0	7.0.0+build.0	8.0.0-pre.0+build.0
major	2.0.0	3.0.0	4.0.0	4.0.0	6.0.0	6.0.0	8.0.0	8.0.0
minor	1.1.0	2.2.0	3.3.0	4.0.0	5.1.0	6.0.0	7.1.0	8.0.0
patch	1.0.1	2.1.1	3.2.2	4.0.0	5.0.1	6.0.0	7.0.1	8.0.0
pre-major	2.0.0-0	3.0.0-0	4.0.0-0	5.0.0-0	6.0.0-0	7.0.0-0	8.0.0-0	9.0.0-0
pre-minor	1.1.0-0	2.2.0-0	3.3.0-0	4.1.0-0	5.1.0-0	6.1.0-0	7.1.0-0	8.1.0-0
pre-patch	1.0.1-0	2.1.1-0	3.2.2-0	4.0.1-0	5.0.1-0	6.0.1-0	7.0.1-0	8.0.1-0
pre-release	1.0.1-0	2.1.1-0	3.2.2-0	4.0.0-1	5.0.1-0	6.0.0-pre.1	7.0.1-0	8.0.0-pre.1
build-release	1.0.0+0	2.1.0+0	3.2.1+0	4.0.0-0+0	5.0.0+1	6.0.0-pre.0+0	7.0.0+build.1	8.0.0-pre.0+build.1

• If a pre level exists and you are bumping major / minor / patch, the pre level is removed and the rest of the version is unchanged
• build levels are removed when any other version level is used other than build

Install

• node.js 10 and greater is supported
• For older versions of node, use the 1.x versions.

npm install -g @theo.gravity/version-bump

Quick start usage

This package comes with the cli version bump strategy included. You can use it via:

version-bump cli --bump <type>

Where <type> is one of the following:

• major
• minor
• patch
• pre-major
• pre-minor
• pre-patch
• pre-release
• pre-*:<colon-sep-tags> (pre-release:alpha:rc)
• build-release
• build-release:<colon-sep-tags> (build-release:qa)

Default is patch level, unless pre/build exists.

If pre/build exists:

• Build is bumped if it exists.
• Pre is bumped if build does not exist, but pre does.

CLI Usage

To use version-bump, a strategy must be selected. You can see a list of options and strategies by calling version-bump without any options.

$ version-bump

Commands:
  version-bump cli [bump]  Performs a version bump based on the --bump flag

Options:
  --version      Show version number                                                                           [boolean]
  --projectRoot  The project root where the version file is found. Default is process.cwd()
                                                                   [default: "/Users/t.gravity/sixfive-cs/version-bump"]
  --configFile   Name of the optional config file, relative to projectRoot.                [default: ".version-bump.ts"]
  --versionFile  The relative path to the JSON version file from projectRoot that contains the "version" property.
                                                                                               [default: "package.json"]
  --help         Show help                                                                                     [boolean]

Get help on a version strategy

$ version-bump cli --help

Performs a version bump based on the --bump flag

Positionals:
  bump  Version type to bump.

        Values can be:
        * major
        * minor
        * patch
        * pre-major
        * pre-minor
        * pre-patch
        * pre-release
        * pre-*:<colon-sep-tags> (pre-release:alpha:rc)
        * build-release
        * build-release:<colon-sep-tags> (build-release:qa)

        Default is the lowest version possible.

Options:
  --version      Show version number                                                                           [boolean]
  --projectRoot  The project root where the version file is found. Default is process.cwd()
                                                                   [default: "/Users/t.gravity/sixfive-cs/version-bump"]
  --configFile   Name of the optional config file, relative to projectRoot.                [default: ".version-bump.ts"]
  --versionFile  The relative path to the JSON version file from projectRoot that contains the "version" property.
                                                                                               [default: "package.json"]
  --help         Show help                                                                                     [boolean]

Custom configuration file

To spare yourself from having to specify command line options each time, you can use a custom config file.

Place .version-bump.ts in the root of your project.

(The file name can be configured with the --configFile option, which is relative to --projectRoot.)

If detected, version-bump will derive options from this file.

With the exception of projectRoot, options defined on the command line will take precedence.

// This is an optional configuration file
// you can use with version-bump.
// If specified, any command line args has priority over the
// values returned in this file.

// All values are optional.
// Do not use the ES6 export default
// since the file is imported using require()
// See command line options for additional available properties
module.exports = {
  // (required) Name of the strategy as found in the strategy list in the CLI
  strategy: 'cli',

  // (optional) Root of the project where the version file is found
  // default is process.cwd()
  projectRoot: () => {
    return process.cwd()
  },

  /**
   * (optional)
   * This is called after the version has been incremented
   * and before the version data is to be converted to a string and saved
   * to the version file
   * Use the opportunity to do any custom-work to the version data
   * eg add a pre-release string, or build string
   * @param {object} versionData
   * @param {number} versionData.major
   * @param {number} versionData.minor
   * @param {number} versionData.patch
   * @param {array|undefined} versionData.pre Ex: ['alpha', 1] becomes x.x.x-alpha.1
   * @param {array|undefined} versionData.build Ex: ['qa', 1234] becomes x.x.x+qa.1234
   * @returns {object}
   */
  onBeforeRelease: (versionData) => {
    versionData.pre = ['alpha', 1]
    return versionData
  },

  // (optional) Version file starting from projectRoot
  // default is package.json
  versionFile: 'myVersionFile.json',

  // Options specific to the strategy you are using
  // root properties can be set to straight values, or (async) functions that return a value
  // this corresponds to the --bump option
  bump: () => {
    return 'minor'
  }
}

With the options above, if myVersionFile.json contained the following:

{
  version: '1.2.3'
}

The above configuration does the following:

• use the strategy cli
• the bump parameter of the cli strategy is set to minor, so the minor version will bump
• after the strategy bumps minor, alpha.1 is added to the version stamp due to the onBeforeRelease callback

This results in:

{
  version: '1.3.0-alpha.1'
}

Additional properties

Aside from the command line options, the config file offers additional properties:

async onBeforeRelease(versionData) : versionData

This is called after the version has been incremented, but before the final write of the version to the file.

You must return the original or updated versionData.

Installing other strategies (plugins)

You can find other strategies by searching for version-bump-plugin on npm.

All strategies should contain version-bump-plugin in the package name

Once you've found the strategy you want, you simply add it by installing it to your node modules directory.

npm install version-bump-plugin-git

You should be able to see the list of strategies by doing

version-bump

In the command line.

Available strategies (plugins)

• version-bump-plugin-git - Bumps version based on last git commit message