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 | [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
|
145 |
|
146 | ```md
|
147 | [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
|
148 | ```
|
149 |
|
150 | ## Team
|
151 |
|
152 | | [![Gregor Martynus](https://github.com/gr2m.png?size=100)](https://github.com/gr2m) | [![Pierre Vanduynslager](https://github.com/pvdlg.png?size=100)](https://github.com/pvdlg) | [![Matt Travi](https://github.com/travi.png?size=100)](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 | | [![Stephan Bönnemann](https://github.com/boennemann.png?size=100)](https://github.com/boennemann) | [![Rolf Erik Lekang](https://github.com/relekang.png?size=100)](https://github.com/relekang) | [![Johannes Jörg Schmidt](https://github.com/jo.png?size=100)](https://github.com/jo) | [![Finn Pauls](https://github.com/finnp.png?size=100)](https://github.com/finnp) | [![Christoph Witzko](https://github.com/christophwitzko.png?size=100)](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>
|