grunt-bumpx

Extended bump version number

Status

Getting Started

This plugin requires Grunt ^0.4.5

If you haven't used Grunt before, be sure to 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 with this command:

npm install grunt-bumpx --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks( 'grunt-bumpx' );

The "bump" task

Overview

In your project's Gruntfile, add a section named bump to the data object passed into grunt.initConfig().

grunt.initConfig({
  bump: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    }
  }
})

This plugin allows you to bump the version number of all the configuration/manifest files (package.json, manifest.json, etc.) in your project. Only JSON files are supported, and each file must have a version field compliant to SemVer guidelines.

Compatibility Issues

As of v0.2.0+, this plugin is no longer backwards compatible with older versions (0.1.x). If you decide to update your version to the latest, be sure to update your configuration files or Grunt will spit on you for sure.

Options

The "level" (array of) modifier functions

The level option accepts the 4 standard levels (major, minor, patch, and prerelease) supported by SemVer. This is usually enough for most projects, but in some cases this could not be enough.

The SemVer standard requires only the main levels of the version number to be positive integers, and it handles them correctly when increments the required level. The problem is that this is not true when referenced to prerelease and build levels.

The prerelease level is handled only incrementing the last integer value found, and there's not a valid way to force the incrementing of different parts of this level. The same is true for the build level (which is ignored and stripped out by SemVer).

Because of that, I've added the support of custom functions for the level option. It's possibile to define a single function or an array of functions. Every function will be called passing the following object as parameter:

If a single function is assigned to level, the value of version will correspond to the old version to be updated. If an array of functions is assigned, the first function into the array will have version equal to the old version, then each subsequently function will receive the partial processed value returned by the functions preceeding the called one. The returned value from the last function in array will be then saved as the final new version number.

The "onBumped" functions

Usually the bumping step is the last one performed before to deploy the project. However, sometimes further steps are required to be done after the version has been updated. The event-like onBumped option can be used just right for this kind of needs.

The defined function(s) will be invoked each time a target file is bumped, with an object parameter containing:

Command Line Options

It's also possible to change the default behaviour of the plugin by using the command line options:

Usage Examples

Default Options

Running the task in this way, each source file's patch level of the version field will be automatically incremented, using an indentation of 2 spaces.

grunt.initConfig({
  bump: {
    options: {},
    src: [ 'package.json', 'manifest.json' ]
  }
})

Custom level and indentation

The formatting of the target JSON file and the level to increment are easily customizable with:

grunt.initConfig({
  bump: {
    options: {
      level: 'minor',
      tabSize: 3
    },
    src: [ 'package.json', 'manifest.json' ]
  }
})

In this way, the target files will have their minor level incremented, and the indentation will be of 3 spaces by soft-tab stop.

Custom modifier and event functions

When more fine-grained adjustements are required, it's possibile to deeply customize the plugin's behaviour:

grunt.initConfig({
  bump: {
    options: {
      level: function ( data ) {
        var levels = data.version.match( /^(\d\.\d\.\d)/ ), 
          newVer = data.semver.inc( levels[1], 'patch' ) + '-rc.1+' + Date.now();
        return newVer;
      },
      onBumped: function ( data ) {
        var currentFile = data.task.filesSrc[ data.index ];
        if ( ( /package.json/ ).test( currentFile ) ) {
          grunt.config( 'pkg', grunt.file.readJSON( currentFile ) );
        }
      }
    },
    src: [ 'package.json', 'manifest.json' ]
  }
})

In this example, the level option has been customized with a function which strips everything out but the main levels from the version number, and returns a new version by incrementing the patch level (using the passed reference to the semver library), concatenating a customized prerelease (-rc.1) and build (Date.now()) levels. The custom function assigned to onBumped, will check if the processed file is package.json and, if so, update the pkg key into the Grunt configuration file by reloading the file.

The example is pretty useless on an daily use, but I hope you catch my point and understand the power of this solution.

Contributing

Any contribution to improve the project and/or expand it is welcome.

If you're interested in contributing to this project, take care to maintain the existing coding style.

The project follows these standard, so please you do it too:

• SemVer for version numbers
• Vandamme for changelog formatting
• EditorConfig for cross-editor configuration

To contribute:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Donating

If you like this work, please consider to support its future development:

BTC: 19ZEWBKuTzNw1opsEN95pG6JuAxuDYq3Nq

LTC: LNoFqJJAM195B4GnNq45JtsWDNtkb8h8WR

Thanks!

Release History

See the CHANGELOG distributed with the project.

License

See the LICENSE distributed with the project.