Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@webpro
webpro committed Nov 15, 2018
1 parent 7a094e2 commit 45bb741
Showing 1 changed file with 73 additions and 47 deletions.
120 changes: 73 additions & 47 deletions README.md
View file
Expand Up @@ -10,10 +10,10 @@ CLI release tool for Git repos and npm packages.
- Bump version (in e.g. `package.json`)
- Generate changelog
- Git commit, tag, push
- [Create release at GitHub](#github-release)
- [Publish to npm](#publishing-to-npm)
- [Create release at GitHub](#github-releases)
- [Upload assets to GitHub release](#release-assets)
- Publish to npm
- [Manage pre-releases](#manage-pre-releases)
- [Manage pre-releases](#managing-pre-releases)
- Support [Conventional Changelog workflows](#custom-or-conventional-changelog)
- [Push build artifacts to a distribution repository](#distribution-repository)

Expand All @@ -31,18 +31,17 @@ CLI release tool for Git repos and npm packages.
- [Interactive vs. non-interactive mode](#interactive-vs-non-interactive-mode)
- [Command hooks](#command-hooks)
- [SSH keys & Git remotes](#ssh-keys--git-remotes)
- [GitHub Release](#github-release)
- [Manage pre-releases](#manage-pre-releases)
- [GitHub Releases](#github-releases)
- [Publishing to npm](#publishing-to-npm)
- [Managing pre-releases](#managing-pre-releases)
- [Custom or Conventional Changelog](#custom-or-conventional-changelog)
- [Distribution repository](#distribution-repository)
- [Notes](#notes)
- [Troubleshooting & debugging](#troubleshooting--debugging)
- [Using release-it programmatically](#using-release-it-programmatically)
- [Examples](#examples)
- [Resources](#resources)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

<!-- tocstop -->

Expand Down Expand Up @@ -98,7 +97,7 @@ release-it minor
release-it 0.8.3
```

See [manage pre-releases](#-manage-pre-releases) for versions like `1.0.0-beta.2` and `npm install my-package@next`.
See [manage pre-releases](#manage-pre-releases) for versions like `1.0.0-beta.2` and `npm install my-package@next`.

You can also do a "dry run", which won't write/touch anything, but does output the commands it would execute, and show the interactivity:

Expand All @@ -108,7 +107,7 @@ release-it --dry-run

## Configuration

Out of the box, release-it has sane defaults, and plenty of options to configure it. Put the options to override in `.release-it.json` in the project root. Example:
Out of the box, release-it has sane defaults, and [plenty of options](conf/release-it.json) to configure it. Put the options to override in `.release-it.json` in the project root. Example:

```
{
Expand All @@ -121,8 +120,10 @@ Out of the box, release-it has sane defaults, and plenty of options to configure
}
```

Notes:

- Only the settings to override need to be in `.release-it.json`. Everything else will fall back to the [default configuration](conf/release-it.json).
- You can use `--config` if you want to use another path for the local `.release-it.json`.
- You can use `--config` if you want to use another path.

Any option can also be set on the command-line, and will have highest priority. Example:

Expand All @@ -138,11 +139,11 @@ release-it --no-npm.publish

## Interactive vs. non-interactive mode

By default, release-it is interactive and allows you to confirm each task before execution:
By default, release-it is **interactive** and allows you to confirm each task before execution:

<img src="./assets/release-it.png?raw=true" height="148">

On a Continuous Integration (CI) environment, or by using the `-n` option, this is fully automated. No prompts are shown and the configured tasks will be executed. This is demonstrated in the first animation above. An overview of the tasks:
By using the `-n` option (i.e. **non-interactive**), the process is fully automated without prompts. The configured tasks will be executed as demonstrated in the first animation above. An overview of the tasks:

| Task | Option | Default | Prompt | Default |
| :---------------------- | :--------------- | :-----: | :------------------- | :-----: |
Expand All @@ -154,20 +155,21 @@ On a Continuous Integration (CI) environment, or by using the `-n` option, this
| GitHub release | `github.release` | `false` | `prompt.src.release` | `Y` |
| npm publish | `npm.publish` | `true` | `prompt.src.publish` | `Y` |

The "Option" + "Default" columns represent default options in non-interactive/CI mode. The "Prompt" + "Default" columns represent the prompts and their default answers in interactive mode. You can still change the answer to either `Y` or `N` as the questions show up (or cancel the process with `Ctrl-c`).
The **Option/Default** columns represent default options in **non-interactive/CI** mode. The **Prompt/Default** columns represent the prompts and their default answers in **interactive** mode. You can still change the answer to either `Y` or `N` as the questions show up (or cancel the process with `Ctrl-c`).

Notes:

Note that, if an option (e.g. `npm.publish`) is `false`, the related prompt (`prompt.src.publish`) will not be shown at all in interactive mode (regardless of its default answer).
- If an option is set to `false`, the related prompt will not be shown at all in interactive mode (regardless of its default answer).
- On a Continuous Integration (CI) environment, the non-interactive mode is activated automatically.

## Command hooks

The command hooks are executed from the root directory of the `src` or `dist` repository, respectively:

- `src.beforeStartCommand`
- `beforeChangelogCommand`
- `buildCommand` - before files are staged for commit
- `buildCommand` (before files are staged for commit)
- `src.afterReleaseCommand`
- `dist.beforeStageCommand` - before files are staged in dist repo
- `dist.afterReleaseCommand`

All commands can use configuration variables (like template strings):

Expand All @@ -178,23 +180,32 @@ All commands can use configuration variables (like template strings):

The variables can be found in the [default configuration](https://github.com/webpro/release-it/blob/master/conf/release-it.json). Additionally, `version`, `latestVersion` and `changelog` are exposed in custom commands. Also the `repo` object (with properties `remote`, `protocol`, `host`, `owner`, `repository` and `project`) is available.

For [distribution repositories](#distribution-repository), two additional hooks are available:

- `dist.beforeStageCommand`
- `dist.afterReleaseCommand`

## SSH keys & Git remotes

The tool assumes SSH keys and Git remotes to be configured correctly. If `git push` works, release-it should work. Otherwise, the following GitHub help pages might be useful: [SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) and [Managing Remotes](https://help.github.com/categories/managing-remotes/).
The tool assumes SSH keys and Git remotes to be configured correctly. If a manual `git push` from the command line works, release-it should be able to do the same.

The following GitHub help pages might be useful: [SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) and [Managing Remotes](https://help.github.com/categories/managing-remotes/).

## GitHub Release
## GitHub Releases

See this project's [releases page](https://github.com/webpro/release-it/releases) for an example. To create [GitHub releases](https://help.github.com/articles/creating-releases/):
The "Releases" tab on GitHub projects links to a page to store the changelog. To add [GitHub releases](https://help.github.com/articles/creating-releases/) in your release-it flow:

- The `github.release` option must be `true`.
- Configure `github.release: true`.
- Obtain a [GitHub access token](https://github.com/settings/tokens) (release-it only needs "repo" access; no "admin" or other scopes).
- Make sure the token is available as an environment variable. Example:

```bash
export GITHUB_TOKEN="f941e0..."
```

Do not put the actual token in the `github.tokenRef` configuration, it should be the name of the environment variable.
Do not put the actual token in the release-it configuration. It will be read from the `GITHUB_TOKEN` environment variable. You can change this variable name by setting the `github.tokenRef` option to something else.

Obviously, release-it uses this feature extensively: [release-it's releases page](https://github.com/webpro/release-it/releases).

### Release assets

Expand All @@ -204,21 +215,38 @@ minified scripts, documentation), provide one or more glob patterns for the `git
```json
"github": {
"release": true,
"assets": "dist/*.zip"
"assets": ["dist/*.zip"]
}
```

## Manage pre-releases
## Publishing to npm

No configuration is needed to publish the package to npm, as `npm.publish` is `true` by default. If a manual `npm publish` from the command line works, release-it should be able to do the same.

In case two-factor authentication (2FA) is enabled for the package, release-it will ask for the one-time password (OTP).

Notes:

- The OTP can be provided from the command line (`--npm.otp=123456`). However, providing the OTP without a prompt basically defeats the purpose of 2FA (also, the OTP expires after short period).
- Getting an `ENEEDAUTH` error while a manual `npm publish` works? Please see [#95](https://github.com/webpro/release-it/issues/95#issuecomment-344919384).

## Managing pre-releases

With release-it, it's easy to create pre-releases: a version of your software that you want to make available, while it's not in the stable semver range yet. Often "alpha", "beta", and "rc" (release candidate) are used as identifier for pre-releases.

For example, if you're working on a new major update for `awesome-pkg` (while the latest release was v1.4.1), and you want others to try your latest beta version:
An example. The `awesome-pkg` is at version 1.4.1, and work is done for a new major update. To publish the latest beta of the new major version:

```
release-it major --preRelease=beta
```

This will tag and release version `2.0.0-beta.0`. This is actually a shortcut for:
This will tag and release version `2.0.0-beta.0`. Notes:

- A normal installation of `awesome-pkg` will still be at version 1.4.1.
- The [npm tag](https://docs.npmjs.com/cli/dist-tag) will be `beta`: install it using `npm install awesome-pkg@beta`
- A GitHub release will be marked as a "Pre-release".

The above command is actually a shortcut for:

```
release-it premajor --preReleaseId=beta --npm.tag=beta --github.preRelease
Expand All @@ -230,20 +258,16 @@ Consecutive beta releases (`v2.0.0-beta.1` and so on) are now easy:
release-it --preRelease=beta
```

Installing the package with npm:

```
npm install awesome-pkg # Installs v1.4.1
npm install awesome-pkg@beta # Installs v2.0.0-beta.1
```

You can still override individual options, e.g. the npm tag being used:

```
release-it --preRelease=rc --npm.tag=next
```

See [semver.org](http://semver.org) for more details about semantic versioning.
Notes:

- By default (in interactive mode), release-it will always ask for your confirmation before publishing the package with the next version.
- See [semver.org](http://semver.org) for more details about semantic versioning.

## Custom or Conventional Changelog

Expand All @@ -259,7 +283,7 @@ If your project follows conventions, such as the [Angular commit guidelines](htt

Please find the [list of available conventions](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages) (`angular`, `ember`, etc).

### Generate a custom changelog
### Generating a custom changelog

With release-it, you can use tools like [conventional-changelog-cli](https://www.npmjs.com/package/conventional-changelog-cli) to generate the changelog for the GitHub release. Make sure that the command defined in the `changelogCommand` option outputs the changelog to `stdout`. In the next example, `beforeChangelogCommand` is also used, to update the `CHANGELOG.md` file. This change will also be included in the release commit.

Expand All @@ -272,7 +296,7 @@ With release-it, you can use tools like [conventional-changelog-cli](https://www
}
```

For this use case, the `safeBump` option was introduced. Set this to `false` to bump `package.json#version` _before_ the `beforeChangelogCommand` is executed, as the `conventional-changelog` tool needs to run from the current version.
For this use case, the `safeBump` option was introduced. Set this to `false` to bump `package.json#version` **before** the `beforeChangelogCommand` is executed, as the `conventional-changelog` tool needs to run from the current version.

## Distribution repository

Expand All @@ -298,13 +322,20 @@ To use this feature, set the `dist.repo` option to a git endpoint. An example co
}
```

With this example, `dist.repo` will be cloned to `.stage`. Then from the source repo `npm run build` is executed, and the generated files at `dist/**.*` will be copied to the `.stage` directory. The result is pushed back to `dist.repo`. Additionally, a GitHub release is created, and the package is published to npm.
With this example:

- The `dist.repo` will be cloned to `.stage`.
- From the root of source repo, `npm run build` is executed.
- The generated files at `dist/**.*` will be copied to the `.stage` directory.
- The result is pushed back to `dist.repo`.
- A GitHub release is created, and the package is published to npm.

## Notes

- The `"private": true` setting in package.json will be respected and the package won't be published to npm.
- By default, untracked files are not added to the release commit. Use `src.addUntrackedFiles: true` to override this behavior.
- You can use `src.pushRepo` option to set an alternative url or name of a remote as in `git push <src.pushRepo>`. By default this is `null` and `git push` is used when pushing to the remote.
- Use `src.pushRepo` to `git push` to a different remote (default: `origin`).
- Use `--disable-metrics` to disable sending some anonymous statistical data.

## Troubleshooting & debugging

Expand All @@ -327,7 +358,10 @@ releaseIt(options).then(output => {

## Examples

- [react-navigation/react-navigation](https://github.com/react-navigation/react-navigation)
- [StevenBlack/hosts](https://github.com/StevenBlack/hosts)
- [react-native-community/react-native-tab-view](https://github.com/react-native-community/react-native-tab-view)
- [callstack/linaria](https://github.com/callstack/linaria)
- [swagger-api/swagger-js](https://github.com/swagger-api/swagger-js)
- [posva/vue-promised](https://github.com/posva/vue-promised)
- [blockchain/blockchain-wallet-v4-frontend](https://github.com/blockchain/blockchain-wallet-v4-frontend)
Expand All @@ -340,15 +374,11 @@ releaseIt(options).then(output => {

- [semver.org](http://semver.org)
- [GitHub Help](https://help.github.com) (→ [About Releases](https://help.github.com/articles/about-releases/))
- [npm Blog: Publishing what you mean to publish](http://blog.npmjs.org/post/165769683050/publishing-what-you-mean-to-publish)
- [npm Blog: Publishing what you mean to publish](https://blog.npmjs.org/post/165769683050/publishing-what-you-mean-to-publish)
- [npm Documentation: package.json](https://docs.npmjs.com/files/package.json)
- [Prereleases and npm](https://medium.com/@mbostock/prereleases-and-npm-e778fc5e2420)
- [Glob Primer (node-glob)](https://github.com/isaacs/node-glob#glob-primer) (release-it uses [globby](https://github.com/sindresorhus/globby#readme))

## Contributing

Please see [CONTRIBUTING.md](./CONTRIBUTING.md).

## Credits

Major dependencies:
Expand All @@ -361,7 +391,3 @@ The following Grunt plugins have been a source of inspiration:

- [grunt-release](https://github.com/geddski/grunt-release)
- [grunt-release-component](https://github.com/walmartlabs/grunt-release-component)

## License

[MIT](http://webpro.mit-license.org/)

0 comments on commit 45bb741

Please sign in to comment.