From 45bb741c962438efa3ce8771df09f0ad68ad8a96 Mon Sep 17 00:00:00 2001 From: Lars Kappert Date: Tue, 13 Nov 2018 17:25:56 +0100 Subject: [PATCH] Update readme --- README.md | 120 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 73 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 2516a37d..719bd68e 100644 --- a/README.md +++ b/README.md @@ -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) @@ -31,8 +31,9 @@ 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) @@ -40,9 +41,7 @@ CLI release tool for Git repos and npm packages. - [Using release-it programmatically](#using-release-it-programmatically) - [Examples](#examples) - [Resources](#resources) -- [Contributing](#contributing) - [Credits](#credits) -- [License](#license) @@ -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: @@ -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: ``` { @@ -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: @@ -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: -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 | | :---------------------- | :--------------- | :-----: | :------------------- | :-----: | @@ -154,9 +155,12 @@ 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 @@ -164,10 +168,8 @@ The command hooks are executed from the root directory of the `src` or `dist` re - `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): @@ -178,15 +180,22 @@ 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: @@ -194,7 +203,9 @@ See this project's [releases page](https://github.com/webpro/release-it/releases 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 @@ -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 @@ -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 @@ -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. @@ -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 @@ -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 `. 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 @@ -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) @@ -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: @@ -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/)