diff --git a/README.md b/README.md index 828ede09..0e0782d7 100644 --- a/README.md +++ b/README.md @@ -78,16 +78,18 @@ Per-project installation as shown above is recommended, but global installs are - From npm: `npm install -g release-it` - From Homebrew: `brew install release-it` -## GitHub Actions +## Videos, articles & examples -Want to use release-it with GitHub Actions to fully automate the whole process? Enjoy this great walk-through: [How to -use GitHub Actions & Release-It to Easily Release Your Code][18] (by [David from Kodaps][19]). +Here's a list of interesting external resources: -→ See [Continuous Integration environments][9] for more details. +- Video: [How to use GitHub Actions & Release-It to Easily Release Your Code][18] +- Article: [Monorepo Semantic Releases][19] ([repo][20]) + +Want to add yours to the list? Just open a pull request! ## Configuration -Out of the box, release-it has sane defaults, and [plenty of options][20] to configure it. Most projects use a +Out of the box, release-it has sane defaults, and [plenty of options][21] to configure it. Most projects use a `.release-it.json` file in the project root, or a `release-it` property in `package.json`. Here's a quick example `.release-it.json`: @@ -103,7 +105,7 @@ Here's a quick example `.release-it.json`: } ``` -→ See [Configuration][21] for more details. +→ See [Configuration][22] for more details. ## Interactive vs. CI mode @@ -121,15 +123,15 @@ Use `--only-version` to use a prompt only to determine the version, and automate How does release-it determine the latest version? -1. For projects with a `package.json`, its `version` will be used (see [npm][22] to skip this). +1. For projects with a `package.json`, its `version` will be used (see [npm][23] to skip this). 2. Otherwise, release-it uses the latest Git tag to determine which version should be released. 3. As a last resort, `0.0.0` will be used as the latest version. Alternatively, a plugin can be used to override this (e.g. to manage a `VERSION` or `composer.json` file): -- [@release-it/bumper][23] to read from or bump the version in any file -- [@release-it/conventional-changelog][24] to get a recommended bump based on commit messages -- [release-it-calver-plugin][25] to use CalVer (Calendar Versioning) +- [@release-it/bumper][24] to read from or bump the version in any file +- [@release-it/conventional-changelog][25] to get a recommended bump based on commit messages +- [release-it-calver-plugin][26] to use CalVer (Calendar Versioning) Add the `--release-version` flag to print the **next** version without releasing anything. @@ -138,35 +140,35 @@ Add the `--release-version` flag to print the **next** version without releasing Git projects are supported well by release-it, automating the tasks to stage, commit, tag and push releases to any Git remote. -→ See [Git][26] for more details. +→ See [Git][27] for more details. ## GitHub Releases GitHub projects can have releases attached to Git tags, containing release notes and assets. There are two ways to add -[GitHub releases][27] in your release-it flow: +[GitHub releases][28] in your release-it flow: 1. Automated (requires a `GITHUB_TOKEN`) 2. Manual (using the GitHub web interface with pre-populated fields) -→ See [GitHub Releases][28] for more details. +→ See [GitHub Releases][29] for more details. ## GitLab Releases GitLab projects can have releases attached to Git tags, containing release notes and assets. To automate [GitLab -releases][29]: +releases][30]: - Configure `gitlab.release: true` -- Obtain a [personal access token][30] (release-it only needs the "api" scope). -- Make sure the token is [available as an environment variable][31]. +- Obtain a [personal access token][31] (release-it only needs the "api" scope). +- Make sure the token is [available as an environment variable][32]. -→ See [GitLab Releases][32] for more details. +→ See [GitLab Releases][33] for more details. ## Changelog By default, release-it generates a changelog, to show and help select a version for the new release. Additionally, this changelog serves as the release notes for the GitHub or GitLab release. -The [default command][20] is based on `git log ...`. This setting (`git.changelog`) can be overridden. To further +The [default command][21] is based on `git log ...`. This setting (`git.changelog`) can be overridden. To further customize the release notes for the GitHub or GitLab release, there's `github.releaseNotes` or `gitlab.releaseNotes`. Make sure any of these commands output the changelog to `stdout`. Note that release-it by default is agnostic to commit message conventions. Plugins are available for: @@ -178,14 +180,14 @@ message conventions. Plugins are available for: To print the changelog without releasing anything, add the `--changelog` flag. -→ See [Changelog][33] for more details. +→ See [Changelog][34] for more details. ## Publish to npm With a `package.json` in the current directory, release-it will let `npm` bump the version in `package.json` (and `package-lock.json` if present), and publish to the npm registry. -→ See [Publish to npm][22] for more details. +→ See [Publish to npm][23] for more details. ## Manage pre-releases @@ -193,7 +195,7 @@ With release-it, it's easy to create pre-releases: a version of your software th it's not in the stable semver range yet. Often "alpha", "beta", and "rc" (release candidate) are used as identifiers for pre-releases. An example pre-release version is `2.0.0-beta.0`. -→ See [Manage pre-releases][34] for more details. +→ See [Manage pre-releases][35] for more details. ## Update or re-run existing releases @@ -223,7 +225,7 @@ Use the optional `:plugin` part in the middle to hook into a life cycle method e The core plugins include `version`, `git`, `npm`, `github`, `gitlab`. Note that hooks like `after:git:release` will not run when either the `git push` failed, or when it is configured not to -be executed (e.g. `git.push: false`). See [execution order][35] for more details on execution order of plugin lifecycle +be executed (e.g. `git.push: false`). See [execution order][36] for more details on execution order of plugin lifecycle methods. All commands can use configuration variables (like template strings). An array of commands can also be provided, they @@ -241,7 +243,7 @@ will run one after another. Some example release-it configuration: } ``` -The variables can be found in the [default configuration][20]. Additionally, the following variables are exposed: +The variables can be found in the [default configuration][21]. Additionally, the following variables are exposed: ```text version @@ -272,7 +274,7 @@ Using Inquirer.js inside custom hook scripts might cause issues (since release-i Use `--dry-run` to show the interactivity and the commands it _would_ execute. -→ See [Dry Runs][36] for more details. +→ See [Dry Runs][37] for more details. ## Troubleshooting & debugging @@ -288,62 +290,62 @@ Since v11, release-it can be extended in many, many ways. Here are some plugins: | Plugin | Description | | ----------------------------------------- | ----------------------------------------------------------------------------- | -| [@release-it/bumper][23] | Read & write the version from/to any file | -| [@release-it/conventional-changelog][24] | Provides recommended bump, conventional-changelog, and updates `CHANGELOG.md` | -| [@release-it/keep-a-changelog][37] | Maintain CHANGELOG.md using the Keep a Changelog standards | -| [@release-it-plugins/lerna-changelog][38] | Integrates lerna-changelog into the release-it pipeline | -| [@release-it-plugins/workspaces][39] | Releases each of your projects configured workspaces | -| [release-it-calver-plugin][25] | Enables Calendar Versioning (calver) with release-it | -| [@grupoboticario/news-fragments][40] | An easy way to generate your changelog file | -| [@j-ulrich/release-it-regex-bumper][41] | Regular expression based version read/write plugin for release-it | +| [@release-it/bumper][24] | Read & write the version from/to any file | +| [@release-it/conventional-changelog][25] | Provides recommended bump, conventional-changelog, and updates `CHANGELOG.md` | +| [@release-it/keep-a-changelog][38] | Maintain CHANGELOG.md using the Keep a Changelog standards | +| [@release-it-plugins/lerna-changelog][39] | Integrates lerna-changelog into the release-it pipeline | +| [@release-it-plugins/workspaces][40] | Releases each of your projects configured workspaces | +| [release-it-calver-plugin][26] | Enables Calendar Versioning (calver) with release-it | +| [@grupoboticario/news-fragments][41] | An easy way to generate your changelog file | +| [@j-ulrich/release-it-regex-bumper][42] | Regular expression based version read/write plugin for release-it | Internally, release-it uses its own plugin architecture (for Git, GitHub, GitLab, npm). -→ See all [release-it plugins on npm][42]. +→ See all [release-it plugins on npm][43]. -→ See [plugins][43] for documentation to write plugins. +→ See [plugins][44] for documentation to write plugins. ## Use release-it programmatically While mostly used as a CLI tool, release-it can be used as a dependency to integrate in your own scripts. See [use -release-it programmatically][44] for example code. +release-it programmatically][45] for example code. ## Example projects using release-it -- [axios/axios][45] -- [blockchain/blockchain-wallet-v4-frontend][46] -- [callstack/react-native-paper][47] -- [ember-cli/ember-cli][48] -- [js-cookie/js-cookie][49] -- [metalsmith/metalsmith][50] -- [mozilla/readability][51] -- [pahen/madge][52] -- [redis/node-redis][53] -- [reduxjs/redux][54] -- [saleor/saleor][55] -- [Semantic-Org/Semantic-UI-React][56] -- [shipshapecode/shepherd][57] -- [StevenBlack/hosts][58] -- [swagger-api/swagger-ui][59] + [swagger-editor][60] -- [tabler/tabler][61] + [tabler-icons][62] -- [youzan/vant][63] -- [Repositories that depend on release-it][64] -- GitHub search for [path:\*\*/.release-it.json][65] +- [axios/axios][46] +- [blockchain/blockchain-wallet-v4-frontend][47] +- [callstack/react-native-paper][48] +- [ember-cli/ember-cli][49] +- [js-cookie/js-cookie][50] +- [metalsmith/metalsmith][51] +- [mozilla/readability][52] +- [pahen/madge][53] +- [redis/node-redis][54] +- [reduxjs/redux][55] +- [saleor/saleor][56] +- [Semantic-Org/Semantic-UI-React][57] +- [shipshapecode/shepherd][58] +- [StevenBlack/hosts][59] +- [swagger-api/swagger-ui][60] + [swagger-editor][61] +- [tabler/tabler][62] + [tabler-icons][63] +- [youzan/vant][64] +- [Repositories that depend on release-it][65] +- GitHub search for [path:\*\*/.release-it.json][66] ## Legacy Node.js The latest major version is v15, supporting Node.js 14 and up (as Node.js v12 is EOL). Use release-it v14 for -environments running Node.js v10 and v12. Also see [CHANGELOG.md][66]. +environments running Node.js v10 and v12. Also see [CHANGELOG.md][67]. ## Links -- See [CHANGELOG.md][66] for major/breaking updates, and [releases][67] for a detailed version history. -- To **contribute**, please read [CONTRIBUTING.md][68] first. -- Please [open an issue][69] if anything is missing or unclear in this documentation. +- See [CHANGELOG.md][67] for major/breaking updates, and [releases][68] for a detailed version history. +- To **contribute**, please read [CONTRIBUTING.md][69] first. +- Please [open an issue][70] if anything is missing or unclear in this documentation. ## License -[MIT][70] +[MIT][71] [1]: #git [2]: #hooks @@ -363,55 +365,56 @@ environments running Node.js v10 and v12. Also see [CHANGELOG.md][66]. [16]: ./docs/npm.md#yarn [17]: ./docs/recipes/monorepo.md [18]: https://www.youtube.com/watch?v=7pBcuT7j_A0 -[19]: https://twitter.com/KodapsAcademy -[20]: ./config/release-it.json -[21]: ./docs/configuration.md -[22]: ./docs/npm.md -[23]: https://github.com/release-it/bumper -[24]: https://github.com/release-it/conventional-changelog -[25]: https://github.com/casmith/release-it-calver-plugin -[26]: ./docs/git.md -[27]: https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases -[28]: ./docs/github-releases.md -[29]: https://docs.gitlab.com/ce/user/project/releases/ -[30]: https://gitlab.com/profile/personal_access_tokens -[31]: ./docs/environment-variables.md -[32]: ./docs/gitlab-releases.md -[33]: ./docs/changelog.md -[34]: ./docs/pre-releases.md -[35]: ./docs/plugins.md#execution-order -[36]: ./docs/dry-runs.md -[37]: https://github.com/release-it/keep-a-changelog -[38]: https://github.com/release-it-plugins/lerna-changelog -[39]: https://github.com/release-it-plugins/workspaces -[40]: https://github.com/grupoboticario/news-fragments -[41]: https://github.com/j-ulrich/release-it-regex-bumper -[42]: https://www.npmjs.com/search?q=keywords:release-it-plugin -[43]: ./docs/plugins.md -[44]: ./docs/recipes/programmatic.md -[45]: https://github.com/axios/axios -[46]: https://github.com/blockchain/blockchain-wallet-v4-frontend -[47]: https://github.com/callstack/react-native-paper -[48]: https://github.com/ember-cli/ember-cli -[49]: https://github.com/js-cookie/js-cookie -[50]: https://github.com/metalsmith/metalsmith -[51]: https://github.com/mozilla/readability -[52]: https://github.com/pahen/madge -[53]: https://github.com/redis/node-redis -[54]: https://github.com/reduxjs/redux -[55]: https://github.com/saleor/saleor -[56]: https://github.com/Semantic-Org/Semantic-UI-React -[57]: https://github.com/shipshapecode/shepherd -[58]: https://github.com/StevenBlack/hosts -[59]: https://github.com/swagger-api/swagger-ui -[60]: https://github.com/swagger-api/swagger-editor -[61]: https://github.com/tabler/tabler -[62]: https://github.com/tabler/tabler-icons -[63]: https://github.com/youzan/vant -[64]: https://github.com/release-it/release-it/network/dependents -[65]: https://github.com/search?q=path%3A**%2F.release-it.json&type=code -[66]: ./CHANGELOG.md -[67]: https://github.com/release-it/release-it/releases -[68]: ./.github/CONTRIBUTING.md -[69]: https://github.com/release-it/release-it/issues/new -[70]: ./LICENSE +[19]: https://medium.com/valtech-ch/monorepo-semantic-releases-db114811efa5 +[20]: https://github.com/b12k/monorepo-semantic-releases +[21]: ./config/release-it.json +[22]: ./docs/configuration.md +[23]: ./docs/npm.md +[24]: https://github.com/release-it/bumper +[25]: https://github.com/release-it/conventional-changelog +[26]: https://github.com/casmith/release-it-calver-plugin +[27]: ./docs/git.md +[28]: https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases +[29]: ./docs/github-releases.md +[30]: https://docs.gitlab.com/ce/user/project/releases/ +[31]: https://gitlab.com/profile/personal_access_tokens +[32]: ./docs/environment-variables.md +[33]: ./docs/gitlab-releases.md +[34]: ./docs/changelog.md +[35]: ./docs/pre-releases.md +[36]: ./docs/plugins.md#execution-order +[37]: ./docs/dry-runs.md +[38]: https://github.com/release-it/keep-a-changelog +[39]: https://github.com/release-it-plugins/lerna-changelog +[40]: https://github.com/release-it-plugins/workspaces +[41]: https://github.com/grupoboticario/news-fragments +[42]: https://github.com/j-ulrich/release-it-regex-bumper +[43]: https://www.npmjs.com/search?q=keywords:release-it-plugin +[44]: ./docs/plugins.md +[45]: ./docs/recipes/programmatic.md +[46]: https://github.com/axios/axios +[47]: https://github.com/blockchain/blockchain-wallet-v4-frontend +[48]: https://github.com/callstack/react-native-paper +[49]: https://github.com/ember-cli/ember-cli +[50]: https://github.com/js-cookie/js-cookie +[51]: https://github.com/metalsmith/metalsmith +[52]: https://github.com/mozilla/readability +[53]: https://github.com/pahen/madge +[54]: https://github.com/redis/node-redis +[55]: https://github.com/reduxjs/redux +[56]: https://github.com/saleor/saleor +[57]: https://github.com/Semantic-Org/Semantic-UI-React +[58]: https://github.com/shipshapecode/shepherd +[59]: https://github.com/StevenBlack/hosts +[60]: https://github.com/swagger-api/swagger-ui +[61]: https://github.com/swagger-api/swagger-editor +[62]: https://github.com/tabler/tabler +[63]: https://github.com/tabler/tabler-icons +[64]: https://github.com/youzan/vant +[65]: https://github.com/release-it/release-it/network/dependents +[66]: https://github.com/search?q=path%3A**%2F.release-it.json&type=code +[67]: ./CHANGELOG.md +[68]: https://github.com/release-it/release-it/releases +[69]: ./.github/CONTRIBUTING.md +[70]: https://github.com/release-it/release-it/issues/new +[71]: ./LICENSE