1 | # Release It! 🚀
|
2 |
|
3 | 🚀 Generic CLI tool to automate versioning and package publishing related tasks:
|
4 |
|
5 | <img align="right" src="./docs/assets/release-it.gif?raw=true" height="280">
|
6 |
|
7 | - Execute test & build commands
|
8 | - Bump version (in e.g. `package.json`)
|
9 | - [Git commit, tag, push](#git)
|
10 | - [Create release at GitHub](#github-releases) or [GitLab](#gitlab-releases)
|
11 | - [Generate changelog](#changelog)
|
12 | - [Publish to npm](#publish-to-npm)
|
13 | - [Manage pre-releases](#manage-pre-releases)
|
14 | - [Hooks](#hooks)
|
15 | - Extend with [plugins](#plugins)
|
16 | - Release from any [CI/CD environment](./docs/ci.md)
|
17 |
|
18 | [![Action Status](https://github.com/release-it/release-it/workflows/Cross-OS%20Tests/badge.svg)](https://github.com/release-it/release-it/actions)
|
19 | [![npm version](https://badge.fury.io/js/release-it.svg)](https://badge.fury.io/js/release-it)
|
20 | [![codecov](https://codecov.io/gh/release-it/release-it/branch/master/graph/badge.svg)](https://codecov.io/gh/release-it/release-it)
|
21 |
|
22 | ## Links
|
23 |
|
24 | - See [CHANGELOG.md](./CHANGELOG.md) for major/breaking updates, and
|
25 | [releases](https://github.com/release-it/release-it/releases) for a detailed version history.
|
26 | - To **contribute**, please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.
|
27 | - Please [open an issue](https://github.com/release-it/release-it/issues/new) if anything is missing or unclear in this
|
28 | documentation.
|
29 |
|
30 | <details>
|
31 | <summary><strong>Table of Contents</strong> (click to expand)</summary>
|
32 |
|
33 |
|
34 |
|
35 | - [Installation](#installation)
|
36 | - [Usage](#usage)
|
37 | - [Configuration](#configuration)
|
38 | - [Interactive vs. CI mode](#interactive-vs-ci-mode)
|
39 | - [Latest version](#latest-version)
|
40 | - [Git](#git)
|
41 | - [GitHub Releases](#github-releases)
|
42 | - [GitLab Releases](#gitlab-releases)
|
43 | - [Changelog](#changelog)
|
44 | - [Publish to npm](#publish-to-npm)
|
45 | - [Manage pre-releases](#manage-pre-releases)
|
46 | - [Hooks](#hooks)
|
47 | - [Plugins](#plugins)
|
48 | - [Distribution repository](#distribution-repository)
|
49 | - [Metrics](#metrics)
|
50 | - [Troubleshooting & debugging](#troubleshooting--debugging)
|
51 | - [Use release-it programmatically](#use-release-it-programmatically)
|
52 | - [Example projects using release-it](#example-projects-using-release-it)
|
53 | - [Resources](#resources)
|
54 |
|
55 |
|
56 |
|
57 | </details>
|
58 |
|
59 | ## Installation
|
60 |
|
61 | Although release-it is a **generic** release tool, installation requires npm. A `package.json` file is not required. The
|
62 | recommended way to install release-it also adds basic configuration. Answer one or two questions and it's ready:
|
63 |
|
64 | ```bash
|
65 | npm init release-it
|
66 | ```
|
67 |
|
68 | Alternatively, install it manually, and add the `release` script to `package.json`:
|
69 |
|
70 | ```bash
|
71 | npm install --save-dev release-it
|
72 | ```
|
73 |
|
74 | ```json
|
75 | {
|
76 | "name": "my-package",
|
77 | "version": "1.0.0",
|
78 | "scripts": {
|
79 | "release": "release-it"
|
80 | },
|
81 | "devDependencies": {
|
82 | "release-it": "*"
|
83 | }
|
84 | }
|
85 | ```
|
86 |
|
87 | Now you can run `npm run release` from the command line (any release-it arguments behind the `--`):
|
88 |
|
89 | ```bash
|
90 | npm run release
|
91 | npm run release -- minor --ci
|
92 | ```
|
93 |
|
94 | ### Global usage
|
95 |
|
96 | Use release-it in any (non-npm) project, take it for a test drive, or install it globally:
|
97 |
|
98 | ```bash
|
99 | # Run release-it from anywhere (without installation)
|
100 | npx release-it
|
101 |
|
102 | # Install globally and run from anywhere
|
103 | npm install --global release-it
|
104 | release-it
|
105 | ```
|
106 |
|
107 | ## Usage
|
108 |
|
109 | Release a new version:
|
110 |
|
111 | ```bash
|
112 | release-it
|
113 | ```
|
114 |
|
115 | You will be prompted to select the new version, and more questions will follow based on your setup. For a "dry run" (to
|
116 | show the interactivity and the commands it _would_ execute):
|
117 |
|
118 | ```bash
|
119 | release-it --dry-run
|
120 | ```
|
121 |
|
122 | Note: read-only commands are still executed (`$ ...`), while the rest is not (`! ...`):
|
123 |
|
124 | ```bash
|
125 | $ git rev-parse --git-dir
|
126 | .git
|
127 | ! git add package.json
|
128 | ! git commit --message="Release 0.8.3"
|
129 | ```
|
130 |
|
131 | ## Configuration
|
132 |
|
133 | Out of the box, release-it has sane defaults, and [plenty of options](./config/release-it.json) to configure it. Put
|
134 | (only) the options to override in a configuration file. This is where release-it looks for configuration:
|
135 |
|
136 | - `.release-it.json`
|
137 | - `.release-it.js` (export the configuration object: `module.exports = {}`)
|
138 | - `.release-it.yaml` (or `.yml`)
|
139 | - `.release-it.toml`
|
140 | - `package.json` (in the `release-it` property)
|
141 |
|
142 | Use `--config` to use another path for the configuration file. An example `.release-it.json`:
|
143 |
|
144 | ```json
|
145 | {
|
146 | "git": {
|
147 | "commitMessage": "chore: release v${version}"
|
148 | },
|
149 | "github": {
|
150 | "release": true
|
151 | }
|
152 | }
|
153 | ```
|
154 |
|
155 | Or in a `release-it` property in `package.json`:
|
156 |
|
157 | ```json
|
158 | {
|
159 | "name": "my-package",
|
160 | "devDependencies": {
|
161 | "release-it": "*"
|
162 | },
|
163 | "release-it": {
|
164 | "github": {
|
165 | "release": true
|
166 | }
|
167 | }
|
168 | }
|
169 | ```
|
170 |
|
171 | Or use YAML in `.release-it.yml`:
|
172 |
|
173 | ```yaml
|
174 | git:
|
175 | requireCleanWorkingDir: false
|
176 | ```
|
177 |
|
178 | Or TOML in `.release-it.toml`:
|
179 |
|
180 | ```toml
|
181 | [hooks]
|
182 | "before:init" = "npm test"
|
183 | ```
|
184 |
|
185 | Any option can also be set on the command-line, and will have highest priority. Example:
|
186 |
|
187 | ```bash
|
188 | release-it minor --git.requireBranch=master --github.release
|
189 | ```
|
190 |
|
191 | Boolean arguments can be negated by using the `no-` prefix:
|
192 |
|
193 | ```bash
|
194 | release-it --no-npm.publish
|
195 | ```
|
196 |
|
197 | ## Interactive vs. CI mode
|
198 |
|
199 | By default, release-it is **interactive** and allows you to confirm each task before execution:
|
200 |
|
201 | <img src="./docs/assets/release-it-interactive.gif?raw=true" height="290">
|
202 |
|
203 | By using the `--ci` option, the process is fully automated without prompts. The configured tasks will be executed as
|
204 | demonstrated in the first animation above. On a Continuous Integration (CI) environment, this non-interactive mode is
|
205 | activated automatically.
|
206 |
|
207 | ## Latest version
|
208 |
|
209 | For projects with a `package.json`, its `version` will be used. Otherwise, release-it uses the latest Git tag to
|
210 | determine which version should be released. In any case, as a last resort, `0.0.0` will be used as the latest version.
|
211 |
|
212 | Use `--no-increment` to not increment the version.
|
213 |
|
214 | Use `--npm.ignoreVersion` to use the latest Git tag.
|
215 |
|
216 | Use `--no-npm` (or `"npm": false`) to ignore and skip bumping `package.json` and skip `npm publish` altogether.
|
217 |
|
218 | Alternatively, a plugin can be used to get the version from anywhere else (e.g. a `VERSION` file). Also see
|
219 | [plugins](./docs/plugins.md).
|
220 |
|
221 | ## Git
|
222 |
|
223 | Git projects are supported well by release-it, automating the tasks to stage, commit, tag and push releases to any Git
|
224 | remote.
|
225 |
|
226 | → See [Git](./docs/git.md) for more details.
|
227 |
|
228 | ## GitHub Releases
|
229 |
|
230 | The "Releases" tab on GitHub projects links to a page to store the changelog cq. release notes. To add
|
231 | [GitHub releases](https://help.github.com/articles/creating-releases) in your release-it flow:
|
232 |
|
233 | - Configure `github.release: true`.
|
234 | - Obtain a [personal access token](https://github.com/settings/tokens) (release-it only needs "repo" access; no "admin"
|
235 | or other scopes).
|
236 | - Make sure the token is [available as an environment variable](./docs/environment-variables.md).
|
237 |
|
238 | → See [GitHub Releases](./docs/github-releases.md) for more details.
|
239 |
|
240 | ## GitLab Releases
|
241 |
|
242 | [GitLab releases](https://docs.gitlab.com/ee/workflow/releases.html#releases) work just like GitHub releases:
|
243 |
|
244 | - Configure `gitlab.release: true`.
|
245 | - Obtain a [personal access token](https://gitlab.com/profile/personal_access_tokens) (release-it only needs the "api"
|
246 | scope).
|
247 | - Make sure the token is [available as an environment variable](./docs/environment-variables.md).
|
248 |
|
249 | → See [GitLab Releases](./docs/gitlab-releases.md) for more details.
|
250 |
|
251 | ## Changelog
|
252 |
|
253 | By default, release-it generates a changelog, to show and help select a version for the new release. Additionally, this
|
254 | changelog serves as the release notes for the GitHub or GitLab release.
|
255 |
|
256 | The [default command](./config/release-it.json) is based on `git log ...`. This setting (`git.changelog`) can be
|
257 | overridden. To customize the release notes for the GitHub or GitLab release, use `github.releaseNotes` or
|
258 | `gitlab.releaseNotes`. Make sure any of these commands output the changelog to `stdout`. Topics include:
|
259 |
|
260 | - GitHub and GitLab Releases
|
261 | - auto-changelog
|
262 | - Conventional Changelog
|
263 | - Keep A Changelog
|
264 |
|
265 | → See [Changelog](./docs/changelog.md) for more details.
|
266 |
|
267 | ## Publish to npm
|
268 |
|
269 | With a `package.json` in the current directory, release-it will let `npm` bump the version in `package.json` (and
|
270 | `package-lock.json` if present), and publish to the npm registry.
|
271 |
|
272 | → See [Publish to npm](./docs/npm.md) for more details.
|
273 |
|
274 | ## Manage pre-releases
|
275 |
|
276 | With release-it, it's easy to create pre-releases: a version of your software that you want to make available, while
|
277 | it's not in the stable semver range yet. Often "alpha", "beta", and "rc" (release candidate) are used as identifier for
|
278 | pre-releases. An example pre-release version is `2.0.0-beta.0`.
|
279 |
|
280 | → See [Manage pre-releases](./docs/pre-releases.md) for more details.
|
281 |
|
282 | ## Hooks
|
283 |
|
284 | Use script hooks to run shell commands at any moment during the release process (such as `before:init` or
|
285 | `after:release`).
|
286 |
|
287 | The format is `[prefix]:[hook]` or `[prefix]:[plugin]:[hook]`:
|
288 |
|
289 | | part | value |
|
290 | | ------ | ------------------------------------------- |
|
291 | | prefix | `before` or `after` |
|
292 | | plugin | `version`, `git`, `npm`, `github`, `gitlab` |
|
293 | | hook | `init`, `bump`, `release` |
|
294 |
|
295 | Use the optional `:plugin` part in the middle to hook into a life cycle method exactly before or after any plugin.
|
296 |
|
297 | The core plugins include `version`, `git`, `npm`, `github`, `gitlab`.
|
298 |
|
299 | See [execution order](./docs/plugins.md#execution-order) for more details on execution order of plugin lifecycle
|
300 | methods.
|
301 |
|
302 | All commands can use configuration variables (like template strings). An array of commands can also be provided, they
|
303 | will run one after another. Some example release-it configuration:
|
304 |
|
305 | ```json
|
306 | {
|
307 | "hooks": {
|
308 | "before:init": ["npm run lint", "npm test"],
|
309 | "after:my-plugin:bump": "./bin/my-script.sh",
|
310 | "after:bump": "npm run build",
|
311 | "after:git:release": "echo After git push, before github release",
|
312 | "after:release": "echo Successfully released ${name} v${version} to ${repo.repository}."
|
313 | }
|
314 | }
|
315 | ```
|
316 |
|
317 | The variables can be found in the [default configuration](./config/release-it.json). Additionally, the following
|
318 | variables are exposed:
|
319 |
|
320 | ```
|
321 | version
|
322 | latestVersion
|
323 | changelog
|
324 | name
|
325 | repo.remote, repo.protocol, repo.host, repo.owner, repo.repository, repo.project
|
326 | ```
|
327 |
|
328 | All variables are available in all hooks. The only exception is that the additional variables listed above are not yet
|
329 | available in the `init` hook.
|
330 |
|
331 | Use `--verbose` to log the output of the commands.
|
332 |
|
333 | For the sake of verbosity and to not complicate matters further, the above table is not complete. The full list of hooks
|
334 | is actually: `init`, `beforeBump`, `bump`, `beforeRelease`, `release` or `afterRelease`. However, hooks like
|
335 | `before:beforeRelease` look weird and are usually not useful in practice.
|
336 |
|
337 | ## Plugins
|
338 |
|
339 | Since v11, release-it can be extended in many, many ways. Here are some plugins:
|
340 |
|
341 | | Plugin | Description |
|
342 | | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
|
343 | | [@release-it/bumper](https://github.com/release-it/bumper) | Read & write the version from/to any file |
|
344 | | [@release-it/conventional-changelog](https://github.com/release-it/conventional-changelog) | Provides recommended bump, conventional-changelog, and updates `CHANGELOG.md` |
|
345 | | [release-it-lerna-changelog](https://github.com/rwjblue/release-it-lerna-changelog) | Integrates lerna-changelog into the release-it pipeline |
|
346 | | [release-it-yarn-workspaces](https://github.com/rwjblue/release-it-yarn-workspaces) | Releases each of your projects configured workspaces |
|
347 | | [@grupoboticario/news-fragments](https://github.com/grupoboticario/news-fragments) | An easy way to generate your changelog file |
|
348 |
|
349 | Internally, release-it uses its own plugin architecture (for Git, GitHub, GitLab, npm).
|
350 |
|
351 | → See all [release-it plugins on npm](https://www.npmjs.com/search?q=keywords:release-it-plugin).
|
352 |
|
353 | → See [plugins](./docs/plugins.md) for more details.
|
354 |
|
355 | ## Distribution repository
|
356 |
|
357 | Some projects use a distribution repository. Generated files (such as compiled assets or documentation) can be
|
358 | distributed to a separate repository. Or to a separate branch, such as a `gh-pages`. Some examples include
|
359 | [shim repositories](https://github.com/components) and a separate
|
360 | [packaged Angular.js repository](https://github.com/angular/bower-angular) for distribution on npm and Bower.
|
361 |
|
362 | The `dist.repo` option was removed in v10, but similar setups can still be achieved. Please see the
|
363 | [distribution repository](./docs/recipes/distribution-repo.md) recipe for example configurations.
|
364 |
|
365 | ## Metrics
|
366 |
|
367 | Use `--disable-metrics` to opt-out of sending some anonymous statistical data to Google Analytics. For details, refer to
|
368 | [lib/metrics.js](./lib/metrics.js). Please consider to not opt-out: more data means more support for future development.
|
369 |
|
370 | ## Troubleshooting & debugging
|
371 |
|
372 | - With `release-it --verbose` (or `-V`), release-it prints every custom script/hook and its output.
|
373 | - With `release-it -VV`, release-it also prints every internal command and its output.
|
374 | - Prepend `DEBUG=release-it:* release-it [...]` to print configuration and more error details.
|
375 |
|
376 | Use `verbose: 2` to have the equivalent of `-VV` on the command line in a configuration file.
|
377 |
|
378 | ## Use release-it programmatically
|
379 |
|
380 | While mostly used as a CLI tool, release-it can be used as a dependency to integrate in your own scripts. See
|
381 | [use release-it programmatically](./docs/recipes/programmatic.md) for example code.
|
382 |
|
383 | ## Example projects using release-it
|
384 |
|
385 | - [react-navigation/react-navigation](https://github.com/react-navigation/react-navigation)
|
386 | - [swagger-api/swagger-ui](https://github.com/swagger-api/swagger-ui) +
|
387 | [swagger-editor](https://github.com/swagger-api/swagger-editor)
|
388 | - [js-cookie/js-cookie](https://github.com/js-cookie/js-cookie)
|
389 | - [StevenBlack/hosts](https://github.com/StevenBlack/hosts)
|
390 | - [youzan/vant](https://github.com/youzan/vant/search?q=release-it)
|
391 | - [antonmedv/fx](https://github.com/antonmedv/fx)
|
392 | - [react-native-community/react-native-tab-view](https://github.com/react-native-community/react-native-tab-view)
|
393 | - [callstack/linaria](https://github.com/callstack/linaria) +
|
394 | [react-native-paper](https://github.com/callstack/react-native-paper)
|
395 | - [tabler/tabler-icons](https://github.com/tabler/tabler-icons)
|
396 | - [blockchain/blockchain-wallet-v4-frontend](https://github.com/blockchain/blockchain-wallet-v4-frontend)
|
397 | - [ember-cli/ember-cli](https://github.com/ember-cli/ember-cli)
|
398 | - [shipshapecode/shepherd](https://github.com/shipshapecode/shepherd)
|
399 | - [Repositories that depend on release-it](https://github.com/release-it/release-it/network/dependents)
|
400 | - GitHub search for
|
401 | [projects with .release-it.json](https://github.com/search?o=desc&q=in%3Apath+.release-it.json&s=indexed&type=Code)
|
402 |
|
403 | ## Resources
|
404 |
|
405 | - [semver.org](https://semver.org)
|
406 | - [GitHub Help](https://help.github.com) (→ [About Releases](https://help.github.com/articles/about-releases))
|
407 | - [npm Blog: Publishing what you mean to publish](https://blog.npmjs.org/post/165769683050/publishing-what-you-mean-to-publish)
|
408 | - [npm Documentation: package.json](https://docs.npmjs.com/files/package.json)
|
409 | - [Prereleases and npm](https://medium.com/@mbostock/prereleases-and-npm-e778fc5e2420)
|
410 | - [Glob Primer (node-glob)](https://github.com/isaacs/node-glob#glob-primer) (release-it uses
|
411 | [globby](https://github.com/sindresorhus/globby#readme))
|