1 | # grunt-release
|
2 | [Grunt](http://gruntjs.com) plugin for automating all the release steps of your node lib or bower component, with optional publishing to npm.
|
3 |
|
4 | This is a fork of https://github.com/geddski/grunt-release.
|
5 |
|
6 | ## Repetition Killed the Cat
|
7 | Releasing a new version of your killer Node/Bower/Component/JS lib looks something like this:
|
8 |
|
9 | 1. bump the version in your `package.json` file.
|
10 | 2. stage the package.json file's change.
|
11 | 3. commit that change with a message like "release 0.6.22".
|
12 | 4. create a new git tag for the release.
|
13 | 5. push the changes out to github.
|
14 | 6. also push the new tag out to github.
|
15 | 7. create a .zip release on github.
|
16 | 8. publish the new version to npm.
|
17 |
|
18 | Cool, right? No! What's wrong with you? Automate all that:
|
19 |
|
20 | ```shell
|
21 | grunt release
|
22 | ```
|
23 |
|
24 | Done. No more github issues from angry people reminding you how often you forget to do one or more of the steps.
|
25 |
|
26 | ## Setup
|
27 | If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
|
28 |
|
29 | ```shell
|
30 | npm install grunt-release --save-dev
|
31 | ```
|
32 |
|
33 | Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
|
34 |
|
35 | ```js
|
36 | grunt.loadNpmTasks('grunt-release');
|
37 | ```
|
38 |
|
39 | ## Using grunt-release
|
40 |
|
41 | **Patch Release:**
|
42 | ```shell
|
43 | grunt release
|
44 | ```
|
45 | or
|
46 | ```shell
|
47 | grunt release:patch
|
48 | ```
|
49 |
|
50 | **Minor Release:**
|
51 | ```shell
|
52 | grunt release:minor
|
53 | ```
|
54 |
|
55 | **Major Release:**
|
56 | ```shell
|
57 | grunt release:major
|
58 | ```
|
59 |
|
60 | **Pre-release**
|
61 | ```shell
|
62 | grunt release:prerelease
|
63 | ```
|
64 |
|
65 | `prerelease` will just update the number after `MAJOR.MINOR.PATCH` (eg: `1.0.0-1`)
|
66 | If you want to add an alphanumeric identifier, you will need to add it by hand.
|
67 | Example: add `-alpha.0` to get something like `1.0.0-alpha.0`. Calling `grunt release:prerelease` will just update the last number to `1.0.0-alpha.1`.
|
68 |
|
69 | **Releasing Unstable/Beta Versions**
|
70 | Sometimes it is useful to publish an 'unstable' or 'beta' version to `npm`, while leaving your last stable release as the default that gets installed on an `npm install`.
|
71 | `npm` accomplishes this using the `--tag myUnstableVersion` flag. You can enable this flag in grunt-release either by setting the `npmtag` option:
|
72 |
|
73 | ```js
|
74 | release: {
|
75 | options: {
|
76 | npmtag: 'canary',
|
77 | }
|
78 | }
|
79 | ```
|
80 |
|
81 | or by passing the CLI arg:
|
82 |
|
83 | ```shell
|
84 | grunt release --npmtag canary
|
85 | ```
|
86 |
|
87 | NOTE: If the tag you pass is **true**, then the tag will be the *new* version number after the bump. Otherwise it will be the string you provided.
|
88 |
|
89 |
|
90 | **Bump multuple files at once**
|
91 |
|
92 | Sometimes you may need to bump multiple files while releasing.
|
93 |
|
94 | ```js
|
95 | release: {
|
96 | options: {
|
97 | additionalFiles: 'bower.json',
|
98 | }
|
99 | }
|
100 | ```
|
101 |
|
102 | The version to bump is set in the master file defined with otpion 'file' (default : package.json).
|
103 | This version will be propagated to every additionalFiles.
|
104 |
|
105 |
|
106 | **Dry Run:**
|
107 | To see what grunt-release does, without really changing anything, use `--no-write` option.
|
108 |
|
109 | ```shell
|
110 | grunt release --no-write
|
111 | ```
|
112 |
|
113 | You'll see something like:
|
114 | ```
|
115 | >> -------RELEASE DRY RUN-------
|
116 | >> bumped version to 0.8.0
|
117 | >> staged package.json
|
118 | >> committed package.json
|
119 | >> created new git tag: 0.8.0
|
120 | >> pushed to remote git repo
|
121 | >> pushed new tag 0.8.0 to remote git repo
|
122 | >> published version 0.8.0 to npm
|
123 | >> created 0.8.0 release on github.
|
124 |
|
125 | Done, without errors.
|
126 | ```
|
127 |
|
128 | ## Options
|
129 | The following are all the release steps, you can disable any you need to:
|
130 |
|
131 | ```js
|
132 | release: {
|
133 | options: {
|
134 | bump: false, //default: true
|
135 | file: 'component.json', //default: package.json
|
136 | add: false, //default: true
|
137 | commit: false, //default: true
|
138 | tag: false, //default: true
|
139 | push: false, //default: true
|
140 | pushTags: false, //default: true
|
141 | npm: false, //default: true
|
142 | npmtag: true, //default: no tag
|
143 | indentation: '\t', //default: ' ' (two spaces)
|
144 | folder: 'folder/to/publish/to/npm', //default project root
|
145 | tagName: 'some-tag-<%= version %>', //default: '<%= version %>'
|
146 | commitMessage: 'check out my release <%= version %>', //default: 'release <%= version %>'
|
147 | tagMessage: 'tagging version <%= version %>', //default: 'Version <%= version %>',
|
148 | github: {
|
149 | repo: 'geddski/grunt-release', //put your user/repo here
|
150 | usernameVar: 'GITHUB_USERNAME', //ENVIRONMENT VARIABLE that contains Github username
|
151 | passwordVar: 'GITHUB_PASSWORD' //ENVIRONMENT VARIABLE that contains Github password
|
152 | }
|
153 | }
|
154 | }
|
155 | ```
|
156 |
|
157 | If you want to use multiline commit messages just pass an array to the `commitMessage` option instead of a string.
|
158 |
|
159 | ### Notes on Github Releases:
|
160 | 1. Yes, you have to use environment variables. I would be a terrible person if I let you check in your username and password into your source code.
|
161 | 2. The [Github Releases API](http://developer.github.com/v3/repos/releases/) is still unstable and may change in the future.
|
162 | 3. You can use an [access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) if you'd rather.
|
163 |
|
164 | For node libs, leave `file` option blank as it will default to `package.json`. For Bower components, set it to `bower.json`.
|
165 |
|
166 | ## License
|
167 | MIT
|