@khatastroffik/grunt-standard-version

grunt-standard-version

Grunt.js plugin with automatic versioning (using semver) and CHANGELOG generation (using standard-version)

Getting Started

This plugin requires Grunt 1.1.0 (it may work with some older versions, though not tested) and is integrating standard-version v7.1.0.

If you haven't used Grunt before, please check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin following the instructions below.

Conventional installation

This Grunt plugin should be installed as a development dependency of your project:

npm install --save-dev khatastroffik/grunt-standard-version 

In your project's Gruntfile.js, add a section named standardVersion to the data object passed into grunt.initConfig(). At least one target (e.g. version below) must be defined. This target will be executed by default if no target is explicitly specified when the task is called:

grunt.initConfig({

  //...

  standardVersion: {
    options: {
      // define the DEFAULT options for ALL targets here
    },
    version: {
      options: {
        // define the options SPECIFIC to THIS target here
      }
    }
  },

  //...

});

note: if multiple targets are defined and the task call doesn't specify any target, then ALL the defined targets will be executed in a row.

To enable i.e. load the plugin, add the following inside your Gruntfile.js file (usually after the configuration above):

// load the plugin
grunt.loadNpmTasks('grunt-standard-version');

To integrate the task i.e. in order to have it called in some workflow, you may also define further (kind of meta) tasks like the following:

grunt.registerTask('versionize', ['standardVersion:version']); // call the task with target 'version'
grunt.registerTask('test-versionize', ['clean', 'versionize', 'nodeunit']); // call the 'versionize' task above

grunt.registerTask('release', ['SOME-TASK-HERE', 'standardVersion:version', 'SOME-TASK-THERE']);

To make the grunt (meta) tasks available per npm, you may add some scripts in your package.jsonfile. E.g.:

"scripts": {
  "test-versionize": "grunt test-versionize",
  "versionize": "grunt versionize",
  "release": "grunt release"
}

Options

Grunt plugin specific option

There's only one specific option continueIfError (default = false) that allows Grunt to keep running following tasks in case "standard-version" has failed - if set to true.

standard-version specific options

All the options declared in standard-version v7.1.0 are valid.

Overview:

option	default/example	short description
infile	"CHANGELOG.md"	name of the file used to track the changelog
releaseCommitMessageFormat	"{{currentTag}}"	the message of the commit (the old "message" option is deprecated). Placeholder "{{currentTag}}" is allowed. Current default is chore(release): {{currentTag}}
header	"EXAMPLE HEADER"	headline for the list of changes ('header' is the replacement for the DEPRECATED 'changelogHeader')
packageFiles	[]	list of files that will be scanned to find the 'current version' information. First version found wins!
bumpFiles	[]	list of files (note: the listed 'packageFiles' will be added internally/automatically to the 'bumpFiles' list) in which the 'current version' information should be bumped
firstRelease	false	set to true for the very first release
sign	false	true if a signature should be used to sign the commits...
noVerify	false	if true, existing git hooks will be bypassed
commitAll	false	if true, all staged files (beside the changelog and bumpfiles) will be added to the commit
silent	false	true to avoid displaying any message to console etc.
tagPrefix	"v"	bump will use this to prefix the new version number
scripts	{ }	see standard-version docs
skip	{ }	see standard-version docs
gitTagFallback	true	if no meta-information file is found (e.g., package.json), a fallback 'version' should be used
releaseAs	""	Specify the release type manually (like "major", "minor", "patch" or a custom value like "1.0")
path	""	Only populate commits with files added, modified... under this path
preset	"angular"	Commit message guideline preset (undefined by default). many different presets exist. see standard-version documentation
verbose	false	output extra log information to console...
dryRun	false	simulate if set to true

Further details: see standard-version default configuration and standard-version commands among others.

Usage of the .versionrc (and alternatives) configuration

The conventional-change-spec v2.1.0 (adopted by standard-version) defines configuration options applicable to the presets i.e. each preset may define it's own "taste" according to the spec.

To apply a custom spec i.e. to define a custom rule set, you may create a .versionrc file in the same directory as the Gruntfile.js. See standard-version Configuration documentation.

grunt-standard-version will merge the 'versionrc' custom rule set with the task configuration in the Gruntfile.js. Rules defined in the gruntfile take absolute precedence over the versionrc configuration. This matches with the CLI behavior.

Note: the option header defined in the conventional-change-spec (see above) is not respected by standard-version 7.1.0. Instead, header is defined as a root option by standard-version. This may change in the future (fix?). See the configuration example below.

Gruntfile Configuration Example

This is an example of the standardVersion task configuration using a target named "version".

grunt.initConfig({

  //...
  standardVersion: {
    options: {
      releaseCommitMessageFormat: 'SuperProject {{currentTag}}',
      prerelease: 'alpha',
      silent: true,
      header: '# This is the changelog of the SuperProject\n\n',
      tagPrefix: "version-",
      releaseAs: 'major',
      preset: 'angular',
      dryRun: true
    },
    version: { 
      options: {
        dryRun: false
      }
    }
  },
  //...

});

Executing the task standardVersion:version as defined above will result in:

• reduced task output to the console
• all bump files updated to the next major version, including a pre-release value e.g. from 1.3.0 to 2.0.0-alpha.0
• CHANGELOG.md will be updated according the 'angular' preset with a header as declared above
• all bumpfiles and the changelog will be commited with the message SuperProject version-2.0.0-alpha.0
• a tag will be created as version-2.0.0-alpha.0