grunt-releaseable

Opinionated software release plugin for Grunt. Use to release projects on NPM, and Bower.

The process used by grunt-releaseable us based on the publish script for Leaflet which releases on NPM and Bower but does not keep the built files in the main branch.

Releasing follows this process.

1. Run test script
2. If it exists, bump versions in bower.json to match package.json
3. Commit the bumped files
4. Checkout a temporary branch to make the build on
5. Run your build script
6. Commit the built files
7. Tag the build with the version number
8. Push the build to the specifcied remote
9. Publish on NPM
10. Checkout master
11. Delete the tempory branch

If you are using GitHub you will have a new tag at the version that will have the built files in the repo but the built files will not be commited into the main (or any other) branch.

If you are following SemVer and releasing on GitHub, your new tag will show up in the releases.

Getting Started

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-releaseable --save-dev

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

grunt.loadNpmTasks('grunt-releaseable');

The "releaseable" task

Overview

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

By default the task will run npm test and npm prepublish when building your repo. Make sure you add them to your package.json like so...

  ...
 
  "scripts": {
    "test": "grunt test",
    "prepublish": "grunt build"
  },
 
  ...

The version you want to release is the version that is CURRENTLY in your package.json. So when you want to do a release. Take the following steps...

1. Manually incriment the version in yoru package.json.
2. Run grunt releaseable.
3. Enjoy your new release.

grunt.initConfig({
  releaseable: {
    release: {
      options: {}
    }
  }
});

Options

options.version

Type: String Default value: version from your package.json. If the version in your package.json is a valid SemVer v will be prepended to your version.

The version to tag with repo with. version inside bower.json will also be bumped if it is in your project root.

options.build

Type: String Default value: 'npm prepublish'

The command to run to build your files for release. Defaults to npm prepublish since you should be a nice citizen and use npm scripts.

options.test

Type: String Default value: 'npm test'

The command to run your tests before building. Defaults to npm test since you should be a nice citizen and use npm scripts.

options.remote

Type: String Default value: 'origin'

The Git remote to push the built tag up to.

options.dryRun

Type: Boolean Default value: false

If true will not actually run commands just print log messages so you can confirm setup is corrent.

options.silent

Type: Boolean Default value: true

If false this will enable verbose output from all shell commands run by grunt releaseable.

options.bumpCommitMsg

Type: Function Default value: function(version){ return 'bumping version to ' + version }

Function used to format the commit message after setting version in bower.json.

options.buildCommitMsg

Type: Function Default value: function(version){ return 'build ' + version }

Function used to format the commit message after building the project for release.

Usage Examples

Default Options

grunt.initConfig({
  releaseable: {
    release: {
      options: {
        version: 'VERSION FROM YOUR package.json',
        build: 'npm prepublish',
        test: 'npm test',
        remote: 'origin',
        mainBranch: 'master',
        dryRun: false,
        silent: true,
        bumpCommitMsg: function(version){ return 'bumping version  to ' + version; },
        buildCommitMsg: function(version){ return 'building ' + version; }
      }
    }
  }
});

Custom Options

This custom setup uses grunt test and grunt build in place of npm test and npm prepublish, always does a dry run, and always pushes to a specific remote.

grunt.initConfig({
  releaseable: {
    release: {
      options: {
        version: 'v1.0.0',
        test: 'grunt test',
        build: 'grunt build',
        remote: '[e-mail]:patrickarlt/grunt-releaseable.git',
        dryRun: true
      }
    }
  },
});

With grunt-bump

If you REALLY don't want to bump the version in your package.json manually you can use grunt-bump.

grunt.initConfig({
  bump: {
    options: {
      files: ['package.json'],
      commit: true,
      commitMessage: 'Release v%VERSION%',
      commitFiles: ['package.json'],
      createTag: false,
      push: true,
      pushTo: 'upstream',
    }
  },
  releaseable: {
    options: {,
      remote: 'upstream',
    }
  }
});

Once you have this setup you can use commands like grunt bump:major and then run grunt releaseable.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Nothing yet)