grunt-release-hg-bower

grunt-release-hg-bower

This plugin automates the release process for mercurial projects that are being packaged using bower.

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-release-hg-bower --save-dev

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

grunt.loadNpmTasks('grunt-release-hg-bower');

The "get_bower_version" task

This task retrieves the current version number of the project as calculated by the commit messages with the version keyword. Can optionally supply a changeset identifier to find an old version or a branch version.

 grunt get_bower_version --changeset=tip

The "get_hg_version_log" task

This task retrieves the Hg log of the project with calculated versions appended to the output. can also take a changeset argument.

 grunt get_hg_version_log --changeset=mybranch

The "which_version" task

This task takes a semver string as the command line argument, and returns any matching mercurial commits.

grunt which_version:1.1.3

The "bower_release" task

Overview

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

grunt.initConfig({
  bower_release: {
    options: {
        githubEndpoint: "https://github.com/<your_github_account_name>/<your_release_repo_name>.git"
    },
    your_target_here: {
        files: [
            //your specific files to be released here (supports globs)...
            {
                src:[
                    '**/*.js',
                    'README.md'
                ]
            },
            //you can also pass an object with a cwd property if you want to strip out folders from a path
            {
                src:['**/*.js', 'themes/default/templates/templatecache.js'] || "src/**/*.js",
                cwd:'dist'
            }
        ]
    }
  },
});

Options

options.githubEndpoint

Type: String

the github endpoint for your bower package.

options.stagingDirectoryName

Type: String Default value: '__bowerGruntStaging'

the folder name where the plugin will clone the release github endpoint and copy your files before releasing them

options.pushToHg

Type: boolean Default value: false

setting this to true will push the commit it makes into the local repo if it finds bower dependency changes and a release with the same version as the current changeset. ommitting this option will default to false

options.buildIgnoreFilename

Type: String Default value: '.buildIgnore'

the plugin will create a file using the supplied name with build information when it finds an existing release and bower dependency changes.

options.buildCommands

Type: Array of object Default value: []

the commands you would like the plugin to run as part of your build process. these are executed in order, after the plugin checks for existing releases and dependency changes, but before releasing the package to the specified git endpoint. a sample of the object parameters is shown in the default options example below. the command can be a string or object with the parameters shown for default and windows platforms. args can be a string of options separated by spaces, or an array with a string for each command line option.

releaseVersion

you can also supply a semver string on the command line as shown below. the plugin will check for an existing release before doing anything. This allow you to jump to any specified version.

grunt bower_release --releaseVersion=1.1.3

Usage Examples

Default Options

Here are the default options (except for build commands which shows a couple of example command objects).

grunt.initConfig({
  bower_release: {
    options: {
        githubEndpoint: "https://github.com/<your_github_account_name>/<your_release_repo_name>.git",
        stagingDirectoryName: "__bowerGruntStaging",
        ticketSystem: undefined,
        pushToHg: false,     //this pushes the buildIgnoreFile to Hg if the build was triggered by an upstream project
        buildIgnoreFilename:".buildIgnore",
        buildCommands:[
            {
                command:
                {
                    default:'npm',
                    win32:'npm.cmd'
                },
                args: 'update',
                workingdir:"./"
            },
            {
                command:'hg',
                args: ['log','-l 2'],
                workingdir:"./"
            }
        ]
    },
    your_target_here: {
        src: [
            //your specific files to be released here...
        ]
    }
  },
});

Fogbugz Integration

In this example, we are turning on the fogbugz integration. If you then specify case(s) in your commit message the bower release will contain links to those cases in its commit message. Here is the format used to match cases in the commit message '/case[s]?.{1}\s*(?:\W*([0-9]+))*/ig'

grunt.initConfig({
  bower_release: {
    options: {
        githubEndpoint: "https://github.com/<your_github_account_name>/<your_release_repo_name>.git",
        ticketSystem: 'fogbugz'
    },
    your_target_here: {
        src: [
            //your specific files to be released here...
        ]
    }
  },
});

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

####Version 1.2.0 added existing release checking and build commands for better CI system support. If the CI system triggers a build from an upstream project, the plugin will check for bower dependency updates and push a commit to Hg to keep Hg and Git versions in sync. It also updates the bower.json and package.json version strings, and writes the installed bower package versions into the bower.json file.

####Version 1.0.0 initial release supports releasing Hg repos to bower using the version information from the commit message. It also supports fogbugz case linking if specified in the commit message.