Extended bump version number
This plugin requires Grunt ~0.4.2
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-devOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks( 'grunt-bumpx' );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.
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.* | Type | Default | Description |
|---|---|---|---|
| level | String |
'patch' |
The version level to increase. Allowed values are: major, minor, patch, and prerelease (case insensitive). Required. |
| level | Function |
function( data ){} |
This can be used in place of the String variant. In this case, the function will be called and its return value assigned to the new version number. |
| level | Array[Function] |
[] |
This can be used in place of the String variant. In this case, each function into the array will be called and the result of the last function defined into the array, assigned to the new version number. |
| tabSize | Number |
2 |
Number of spaces (soft tab) to be used for indenting the targeted JSON file. |
| hardTab | Boolean |
false |
Whether hard tabs (\t) have to be used in place of soft tabs. This option has priority over options.tabSize. (If both options are defined and hardTab is set to true, then hard tabs will be used.) |
| onBumped | Array[Function] |
[] |
Functions to call once the version number has been incremented. (Called for each target). |
| onBumped | Function |
function( data ){} |
This can be used in place of the Array[Function] variant. In this case, only a function is called once the version number is incremented. (Called for each target). |
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:
| Key | Type | Description |
|---|---|---|
| semver | Object |
A reference to the semver library, which is used by this plugin and can be used internally to the function for whatever we want to do |
| task | Object |
A reference to the task object |
| index | Number |
The index of currently processed file inside the source files array |
| version | String |
The (temporary) version number to update |
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.
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:
| Key | Type | Description |
|---|---|---|
| task | Object |
A reference to the task object |
| index | Number |
The index of currently processed file inside the source files array |
| version | String |
The updated version number |
It's also possible to change the default behaviour of the plugin by using the command line options:
| Option | Description |
|---|---|
--level |
Specifies the level we want to increment. Allowed values for this option are the standard major, minor, patch, and prerelease. In addition to these values, a further value is supported: if for any reason you need to totally change the version number, just pass to this option the wanted version number which must be a valid SemVer version number. This option will have precedence over the one defined into the configuration file. |
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: {},
files: [ 'package.json', 'manifest.json' ]
}
})The formatting of the target JSON file and the level to increment are easily customizable with:
grunt.initConfig({
bump: {
options: {
level: 'minor',
tabSize: 3
},
files: [ '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.
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 ) );
}
}
},
files: [ '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.
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:
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
If you like this work, please consider to support its future development:
BTC: 19ZEWBKuTzNw1opsEN95pG6JuAxuDYq3Nq
LTC: LNoFqJJAM195B4GnNq45JtsWDNtkb8h8WR
Thanks!
See the CHANGELOG distributed with the project.
See the LICENSE distributed with the project.