| 1 | <h1 align="center" style="border-bottom: none;">📦🚀 semantic-release</h1>
|
| 2 | <h3 align="center">Fully automated version management and package publishing</h3>
|
| 3 | <p align="center">
|
| 4 | <a href="https://github.com/semantic-release/semantic-release/discussions">
|
| 5 | <img alt="Join the community on GitHub Discussions" src="https://img.shields.io/badge/Join%20the%20community-on%20GitHub%20Discussions-blue">
|
| 6 | </a>
|
| 7 | <a href="https://github.com/semantic-release/semantic-release/actions?query=workflow%3ATest+branch%3Amaster">
|
| 8 | <img alt="Build states" src="https://github.com/semantic-release/semantic-release/workflows/Test/badge.svg">
|
| 9 | </a>
|
| 10 | <a href="#badge">
|
| 11 | <img alt="semantic-release: angular" src="https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release">
|
| 12 | </a>
|
| 13 | </p>
|
| 14 | <p align="center">
|
| 15 | <a href="https://www.npmjs.com/package/semantic-release">
|
| 16 | <img alt="npm latest version" src="https://img.shields.io/npm/v/semantic-release/latest.svg">
|
| 17 | </a>
|
| 18 | <a href="https://www.npmjs.com/package/semantic-release">
|
| 19 | <img alt="npm next version" src="https://img.shields.io/npm/v/semantic-release/next.svg">
|
| 20 | </a>
|
| 21 | <a href="https://www.npmjs.com/package/semantic-release">
|
| 22 | <img alt="npm beta version" src="https://img.shields.io/npm/v/semantic-release/beta.svg">
|
| 23 | </a>
|
| 24 | </p>
|
| 25 |
|
| 26 | **semantic-release** automates the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package.
|
| 27 |
|
| 28 | This removes the immediate connection between human emotions and version numbers, strictly following the [Semantic Versioning](http://semver.org) specification and communicating the **impact** of changes to consumers.
|
| 29 |
|
| 30 | > Trust us, this will change your workflow for the better. – [egghead.io](https://egghead.io/lessons/javascript-how-to-write-a-javascript-library-automating-releases-with-semantic-release)
|
| 31 |
|
| 32 | ## Highlights
|
| 33 |
|
| 34 | - Fully automated release
|
| 35 | - Enforce [Semantic Versioning](https://semver.org) specification
|
| 36 | - New features and fixes are immediately available to users
|
| 37 | - Notify maintainers and users of new releases
|
| 38 | - Use formalized commit message convention to document changes in the codebase
|
| 39 | - Publish on different distribution channels (such as [npm dist-tags](https://docs.npmjs.com/cli/dist-tag)) based on git merges
|
| 40 | - Integrate with your [continuous integration workflow](docs/recipes/release-workflow/README.md#ci-configurations)
|
| 41 | - Avoid potential errors associated with manual releases
|
| 42 | - Support any [package managers and languages](docs/recipes/release-workflow/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
|
| 43 | - Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
|
| 44 |
|
| 45 | ## How does it work?
|
| 46 |
|
| 47 | ### Commit message format
|
| 48 |
|
| 49 | **semantic-release** uses the commit messages to determine the consumer impact of changes in the codebase.
|
| 50 | Following formalized conventions for commit messages, **semantic-release** automatically determines the next [semantic version](https://semver.org) number, generates a changelog and publishes the release.
|
| 51 |
|
| 52 | By default, **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format).
|
| 53 | The commit message format can be changed with the [`preset` or `config` options](docs/usage/configuration.md#options) of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins.
|
| 54 |
|
| 55 | Tools such as [commitizen](https://github.com/commitizen/cz-cli) or [commitlint](https://github.com/conventional-changelog/commitlint) can be used to help contributors and enforce valid commit messages.
|
| 56 |
|
| 57 | The table below shows which commit message gets you which release type when `semantic-release` runs (using the default configuration):
|
| 58 |
|
| 59 | | Commit message | Release type |
|
| 60 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
| 61 | | `fix(pencil): stop graphite breaking when too much pressure applied` | ~~Patch~~ Fix Release |
|
| 62 | | `feat(pencil): add 'graphiteWidth' option` | ~~Minor~~ Feature Release |
|
| 63 | | `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release <br /> (Note that the `BREAKING CHANGE: ` token must be in the footer of the commit) |
|
| 64 |
|
| 65 | ### Automation with CI
|
| 66 |
|
| 67 | **semantic-release** is meant to be executed on the CI environment after every successful build on the release branch.
|
| 68 | This way no human is directly involved in the release process and the releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org).
|
| 69 |
|
| 70 | ### Triggering a release
|
| 71 |
|
| 72 | For each new commit added to one of the release branches (for example: `master`, `next`, `beta`), with `git push` or by merging a pull request or merging from another branch, a CI build is triggered and runs the `semantic-release` command to make a release if there are codebase changes since the last release that affect the package functionalities.
|
| 73 |
|
| 74 | **semantic-release** offers various ways to control the timing, the content and the audience of published releases.
|
| 75 | See example workflows in the following recipes:
|
| 76 |
|
| 77 | - [Using distribution channels](docs/recipes/release-workflow/distribution-channels.md#publishing-on-distribution-channels)
|
| 78 | - [Maintenance releases](docs/recipes/release-workflow/maintenance-releases.md#publishing-maintenance-releases)
|
| 79 | - [Pre-releases](docs/recipes/release-workflow/pre-releases.md#publishing-pre-releases)
|
| 80 |
|
| 81 | ### Release steps
|
| 82 |
|
| 83 | After running the tests, the command `semantic-release` will execute the following steps:
|
| 84 |
|
| 85 | | Step | Description |
|
| 86 | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
| 87 | | Verify Conditions | Verify all the conditions to proceed with the release. |
|
| 88 | | Get last release | Obtain the commit corresponding to the last release by analyzing [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). |
|
| 89 | | Analyze commits | Determine the type of release based on the commits added since the last release. |
|
| 90 | | Verify release | Verify the release conformity. |
|
| 91 | | Generate notes | Generate release notes for the commits added since the last release. |
|
| 92 | | Create Git tag | Create a Git tag corresponding to the new release version. |
|
| 93 | | Prepare | Prepare the release. |
|
| 94 | | Publish | Publish the release. |
|
| 95 | | Notify | Notify of new releases or errors. |
|
| 96 |
|
| 97 | ## Requirements
|
| 98 |
|
| 99 | In order to use **semantic-release** you need:
|
| 100 |
|
| 101 | - To host your code in a [Git repository](https://git-scm.com)
|
| 102 | - Use a Continuous Integration service that allows you to [securely set up credentials](docs/usage/ci-configuration.md#authentication)
|
| 103 | - A Git CLI version that meets [our version requirement](docs/support/git-version.md) installed in your Continuous Integration environment
|
| 104 | - A [Node.js](https://nodejs.org) version that meets [our version requirement](docs/support/node-version.md) installed in your Continuous Integration environment
|
| 105 |
|
| 106 | ## Documentation
|
| 107 |
|
| 108 | - Usage
|
| 109 | - [Getting started](docs/usage/getting-started.md#getting-started)
|
| 110 | - [Installation](docs/usage/installation.md#installation)
|
| 111 | - [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
|
| 112 | - [Configuration](docs/usage/configuration.md#configuration)
|
| 113 | - [Plugins](docs/usage/plugins.md)
|
| 114 | - [Workflow configuration](docs/usage/workflow-configuration.md)
|
| 115 | - [Shareable configurations](docs/usage/shareable-configurations.md)
|
| 116 | - Extending
|
| 117 | - [Plugins](docs/extending/plugins-list.md)
|
| 118 | - [Shareable configuration](docs/extending/shareable-configurations-list.md)
|
| 119 | - Recipes
|
| 120 | - [CI configurations](docs/recipes/ci-configurations/README.md)
|
| 121 | - [Git hosted services](docs/recipes/git-hosted-services/README.md)
|
| 122 | - [Release workflow](docs/recipes/release-workflow/README.md)
|
| 123 | - Developer guide
|
| 124 | - [JavaScript API](docs/developer-guide/js-api.md)
|
| 125 | - [Plugins development](docs/developer-guide/plugin.md)
|
| 126 | - [Shareable configuration development](docs/developer-guide/shareable-configuration.md)
|
| 127 | - Support
|
| 128 | - [Resources](docs/support/resources.md)
|
| 129 | - [Frequently Asked Questions](docs/support/FAQ.md)
|
| 130 | - [Troubleshooting](docs/support/troubleshooting.md)
|
| 131 | - [Node version requirement](docs/support/node-version.md)
|
| 132 | - [Node Support Policy](docs/support/node-support-policy.md)
|
| 133 |
|
| 134 | ## Get help
|
| 135 |
|
| 136 | - [GitHub Discussions](https://github.com/semantic-release/semantic-release/discussions)
|
| 137 | - [Stack Overflow](https://stackoverflow.com/questions/tagged/semantic-release)
|
| 138 | - [Twitter](https://twitter.com/SemanticRelease)
|
| 139 |
|
| 140 | ## Badge
|
| 141 |
|
| 142 | Let people know that your package is published using **semantic-release** and which [commit-convention](#commit-message-format) is followed by including this badge in your readme.
|
| 143 |
|
| 144 | [](https://github.com/semantic-release/semantic-release)
|
| 145 |
|
| 146 | ```md
|
| 147 | [](https://github.com/semantic-release/semantic-release)
|
| 148 | ```
|
| 149 |
|
| 150 | ## Team
|
| 151 |
|
| 152 | | [](https://github.com/gr2m) | [](https://github.com/pvdlg) | [](https://github.com/travi) |
|
| 153 | | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|
| 154 | | [Gregor Martynus](https://github.com/gr2m) | [Pierre Vanduynslager](https://github.com/pvdlg) | [Matt Travi](https://github.com/travi) |
|
| 155 |
|
| 156 | ## Alumni
|
| 157 |
|
| 158 | | [](https://github.com/boennemann) | [](https://github.com/relekang) | [](https://github.com/jo) | [](https://github.com/finnp) | [](https://github.com/christophwitzko) |
|
| 159 | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
| 160 | | [Stephan Bönnemann](https://github.com/boennemann) | [Rolf Erik Lekang](https://github.com/relekang) | [Johannes Jörg Schmidt](https://github.com/jo) | [Finn Pauls](https://github.com/finnp) | [Christoph Witzko](https://github.com/christophwitzko) |
|
| 161 |
|
| 162 | <p align="center">
|
| 163 | <img alt="Kill all humans" src="media/bender.png">
|
| 164 | </p>
|