8d575654c2
- Remove `@semantic-release/condition-travis` from the default plugins - Verify the current branch in the core - Verify the build is not triggered by a PR in the core - Run in dry-run mode if not triggered on CI - Dry-run mode runs the `verifyConditions` plugins, allowing to detect configuration error locally - Return without error when no version has to be released due to no changes - Return without error if the build is triggered from a PR - Return without error if the current branch is not the configured branch - CLI return with exit code 1 if there is a `semanticReleaseError`, allowing to fail builds in case of config error, missing token etc... BREAKING CHANGE: `semantic-release` doesn't make sure it runs only on one Travis job anymore. The CI configuration has to be done such that `semantic-release` - runs only once per build - runs only after all tests are successful on every jobs of the build - runs on Node >=8 This can easily be done with [travis-deploy-once](https://github.com/semantic-release/travis-deploy-once). Migration Guide Modify your `.travis.yml` to use `travis-deploy-once`. Replace: ```yaml after_success: - npm run semantic-release ``` by: Replace ```yaml after_success: - npm install -g travis-deploy-once@4 - travis-deploy-once "npm run semantic-release" ```
338 lines
22 KiB
Markdown
338 lines
22 KiB
Markdown
# :package::rocket: semantic-release
|
||
|
||
**fully automated package publishing**
|
||
|
||
> **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)
|
||
|
||
[](https://gitter.im/semantic-release/semantic-release?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||
[](https://www.npmjs.com/package/semantic-release)
|
||
[](https://greenkeeper.io/)
|
||
[](https://github.com/semantic-release/semantic-release/blob/master/LICENSE)
|
||
[](https://github.com/prettier/prettier)
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
[](http://commitizen.github.io/cz-cli/)
|
||
|
||
[](https://travis-ci.org/semantic-release/semantic-release)
|
||
[](https://codecov.io/gh/semantic-release/semantic-release)
|
||
|
||
Out of the box this is just about _commit-messages_, but you can do so much more.
|
||
|
||
* **Detect breaking changes** using the test suite of your last release: [cracks](https://github.com/semantic-release/cracks)
|
||
* Detect breaking changes using your dependents’ test suites: [Help out! Implement the **dont-break** plugin](https://github.com/semantic-release/semantic-release/issues/65)
|
||
* Detect breaking changes diffing your JSDoc interface: [Help out! Implement the **india** plugin](https://github.com/semantic-release/semantic-release/issues/66)
|
||
* Abort releases with **insufficient test coverage**: [Help out! Implement the **istanbul** plugin](https://github.com/semantic-release/semantic-release/issues/68)
|
||
* Abort releases with **vulnerable dependencies** in the tree: [Help out! Implement the **nsp** plugin](https://github.com/semantic-release/semantic-release/issues/67)
|
||
* Everything you can imagine: [Build Plugins!](https://github.com/semantic-release/semantic-release#plugins)
|
||
|
||
| Commands | Comment
|
||
--- | --- | ---
|
||
| **manual/before** | <pre><code><div>npm version major</div><div>git push origin master --tags</div><div>npm publish</div></code></pre> | You **manually decide** what the **next version** is. You have to remember what major, minor and patch means. You have to remember to push both commits and tags. You have to wait for the CI to pass. |
|
||
| **semantic-release/after** | <pre><code><div>git commit -m "fix: <message>"</div><div>git push</div></code></pre> | You **describe the changes** you’ve made. A new version is automatically published with the correct version number.
|
||
|
||
This removes the immediate connection between human emotions and version numbers, so strictly following the [SemVer](http://semver.org/) spec is not a problem anymore – and that’s ultimately `semantic-release`’s goal.
|
||
|
||
<table>
|
||
<tr>
|
||
<th colspan="2">
|
||
“How to Write a JavaScript Library - Automating Releases with semantic-release” – egghead.io
|
||
</th>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
<a href="https://egghead.io/lessons/javascript-how-to-write-a-javascript-library-automating-releases-with-semantic-release"><img src="https://cloud.githubusercontent.com/assets/908178/9730739/7b1da5d8-5610-11e5-88b6-5c75fdda7ee2.png" alt="egghead.io session"></a>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
A free egghead.io tutorial series on how to write an open source library featuring semantic-release.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<th>
|
||
“We fail to follow SemVer – and why it needn’t matter”
|
||
</th>
|
||
<th>
|
||
“semantic-release Q&A with Kent C. Dodds”
|
||
</th>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<a href="https://www.youtube.com/watch?v=tc2UgG5L7WM&index=6&list=PLFZ5NyC0xHDaaTy6tY9p0C0jd_rRRl5Zm"><img alt="JSConfBP Talk" src="https://cloud.githubusercontent.com/assets/908178/9428178/c337ed26-49a2-11e5-8ad0-a602500a65bf.png"></a>
|
||
</td>
|
||
<td>
|
||
<a href="https://www.youtube.com/watch?v=g6y3DnhkjrI"><img alt="Hangout on Air with Kent C. Dodds" src="https://cloud.githubusercontent.com/assets/908178/9428179/c3387318-49a2-11e5-9f5f-dccd3fbb0c1d.png"></a>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
This talk gives you a complete introduction to the underlying concepts of this module. 38:30
|
||
</td>
|
||
<td>
|
||
A “Hangouts on Air” conversation with hands on questions and answers about how to use semantic-release. 53:52
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## How does it work?
|
||
|
||
Instead of writing [meaningless commit messages](http://whatthecommit.com/), we can take our time to think about the changes in the codebase and write them down. Following formalized conventions it is then possible to generate a helpful changelog and to derive the next semantic version number from them.
|
||
|
||
When `semantic-release` is set up it will do that after every successful continuous integration build of your master branch (or any other branch you specify) and publish the new version for you. This way no human is directly involved in the release process and your releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org/).
|
||
|
||
If you fear the loss of control over timing and marketing implications of software releases you should know that `semantic-release` supports [release channels](https://github.com/npm/npm/issues/2718) using `npm`’s [dist-tags](https://docs.npmjs.com/cli/dist-tag). This way you can keep control over what your users end up using by default, you can decide when to promote an automatically released version to the stable channel, and you can choose which versions to write blogposts and tweets about. You can use the same mechanism to [support older versions of your software](https://gist.github.com/boennemann/54042374e49c7ade8910), for example with important security fixes.
|
||
|
||
When pushing new commits with `git push` a CI build is triggered. After running the tests the command `semantic-release` will execute the following tasks in series:
|
||
|
||
| Step | Description |
|
||
| ------------------ | ------------------------------------------------------------------------------------------- |
|
||
| Verify Conditions | Run the [verifyConditions](#verifyconditions) plugin |
|
||
| Get last release | Obtain last release with the [getLastRelease](#getlastrelease) plugin |
|
||
| Analyze commits | Determine the type of release to do with the [analyzeCommits](#analyzecommits) plugin |
|
||
| Verify release | Call the [verifyRelease](#verifyrelease) plugin |
|
||
| Generate notes | Generate release notes with plugin [generateNotes](#generatenotes) |
|
||
| Publish | Call the [publish](#publish) plugin |
|
||
|
||
## Default Commit Message Format
|
||
|
||
This module ships with the [AngularJS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit) and changelog generator, but you can [define your own](#plugins) style.
|
||
|
||
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
|
||
format that includes a **type**, a **scope** and a **subject** ([full explanation](https://github.com/stevemao/conventional-changelog-angular/blob/master/convention.md)):
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
<BLANK LINE>
|
||
<body>
|
||
<BLANK LINE>
|
||
<footer>
|
||
```
|
||
|
||
You can simplify using this convention for yourself and contributors by using [commitizen](https://github.com/commitizen/cz-cli) and [commitlint](https://github.com/marionebl/commitlint) or [semantic-git-commit-cli](https://github.com/JPeer264/node-semantic-git-commit-cli).
|
||
|
||
### Patch Release
|
||
|
||
```
|
||
fix(pencil): stop graphite breaking when too much pressure applied
|
||
```
|
||
|
||
### ~~Minor~~ Feature Release
|
||
|
||
```
|
||
feat(pencil): add 'graphiteWidth' option
|
||
```
|
||
|
||
### ~~Major~~ Breaking Release
|
||
|
||
```
|
||
perf(pencil): remove graphiteWidth option
|
||
|
||
BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.
|
||
```
|
||
|
||
## Setup
|
||
|
||
[](https://nodei.co/npm/semantic-release/)
|
||
|
||
```bash
|
||
npm install -g semantic-release-cli
|
||
|
||
cd your-module
|
||
semantic-release-cli setup
|
||
```
|
||
|
||
|
||
|
||
_[This is what happens under the hood.](https://github.com/semantic-release/cli#what-it-does)_
|
||
|
||
## Options
|
||
|
||
You can pass options either via command line (in [kebab-case](https://lodash.com/docs#kebabCase)) or in the `release` field of your `package.json` (in [camelCase](https://lodash.com/docs#camelCase)). Alternatively the configuration can also be defined in `.releaserc.yml`, `.releaserc.js`, `.releaserc.js` or `release.config.js`.
|
||
|
||
The following two examples are the same, but CLI arguments take precedence.
|
||
|
||
##### CLI
|
||
```bash
|
||
semantic-release --branch next
|
||
```
|
||
|
||
##### package.json
|
||
```json
|
||
"release": {
|
||
"branch": "next"
|
||
}
|
||
```
|
||
```bash
|
||
semantic-release
|
||
```
|
||
|
||
These options are currently available:
|
||
- `branch`: The branch on which releases should happen. Default: `'master'`
|
||
- `repositoryUrl`: The git repository URL. Default: `repository` property in `package.json` or git origin url. Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)). If the [Github plugin](https://github.com/semantic-release/github) is used the URL must be a valid Github URL that include the `owner`, the `repository` name and the `host`. The Github shorthand URL is not supported.
|
||
- `dry-run`: Dry-run mode, skip publishing, print next version and release notes
|
||
- `extends`: Array of module or files path containing a shareable configuration. Options defined via CLI or in the `release` property will take precedence over the one defined in a shareable configuration.
|
||
- `debug`: Output debugging information
|
||
|
||
_A few notes on `npm` config_:
|
||
1. The `npm` token can only be defined in the environment as `NPM_TOKEN`, because that’s where `npm` itself is going to read it from.
|
||
2. In order to publish to a different `npm` registry you can specify that inside the `package.json`’s [`publishConfig`](https://docs.npmjs.com/files/package.json#publishconfig) field.
|
||
3. If you want to use another dist-tag for your publishes than `'latest'` you can specify that inside the `package.json`’s [`publishConfig`](https://docs.npmjs.com/files/package.json#publishconfig) field.
|
||
|
||
## Plugins
|
||
|
||
There are numerous steps where you can customize `semantic-release`’s behavior using plugins. A plugin is a regular [option](#options), but passed inside the `release` block of `package.json`:
|
||
|
||
```json
|
||
{
|
||
"release": {
|
||
"analyzeCommits": "npm-module-name",
|
||
"generateNotes": "./path/to/a/local/module",
|
||
"verifyConditions": {
|
||
"path": "./path/to/a/module",
|
||
"additional": "config"
|
||
},
|
||
"globalPluginOptions": "globalConfig"
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
semantic-release --analyze-commits="npm-module-name"
|
||
```
|
||
|
||
**Note**: The plugin CLI arguments can be only used to override the plugins to use. Plugins options cannot be defined via CLI arguments and must be defined in the main configuration file or in a shareable config.
|
||
|
||
A plugin itself is an async function that always receives three arguments.
|
||
|
||
```js
|
||
module.exports = function (pluginConfig, config, callback) {}
|
||
```
|
||
|
||
- `pluginConfig`: If the user of your plugin specifies additional plugin config in the `package.json` (see the `verifyConditions` example above) then it’s this object. Options defined directly under `release` will be passed to each plugins. Options defined within a plugin will passed only to that instance of the plugin.
|
||
- `config`: A config object containing a lot of information to act upon.
|
||
- `options`: `semantic-release` options like `repositoryUrl`, or `branch`
|
||
- For certain plugins the `config` object contains even more information. See below.
|
||
|
||
### `analyzeCommits`
|
||
|
||
This plugin is responsible for determining the type of the next release. It additionally receives a `commits` array inside `config`. One commit is an object with a `message` and `hash` property. Call the callback with `'major'`, `'premajor'`, `'minor'`, `'preminor'`, `'patch'`, `'prepatch'`, `'prerelease'`, or `null` if nothing changed.
|
||
|
||
While it may be tempting to use `'prepatch'`, `'preminor'` & `'prerelease'` as part of a release process, this is strongly discouraged. A better approach is to use [dist-tags](https://docs.npmjs.com/cli/dist-tag) to create release channels (such as 'latest', 'next', 'stable') and to return only `'major'`, `'premajor'` and `'minor'` from the commit analyzer.
|
||
|
||
Have a look at the [default implementation](https://github.com/semantic-release/commit-analyzer/).
|
||
|
||
### `verifyConditions`
|
||
|
||
This plugins is responsible for verifying that a release should happen in the first place.
|
||
The default implementations are:
|
||
- [travis](https://github.com/semantic-release/condition-travis/): verifies that the publish is happening on Travis, that it’s the right branch, and that all other build jobs succeeded.
|
||
- [github](https://github.com/semantic-release/github/): verifies a Github authentication is set and valid.
|
||
- [npm](https://github.com/semantic-release/npm/): verifies an npm authentication is set and valid.
|
||
|
||
Passing an array of plugins will run them in series.
|
||
|
||
### `verifyRelease`
|
||
|
||
This plugin is responsible for verifying a release that was determined before and is about to be published. There is no default implementation. It additionally receives `nextRelease`, `lastRelease` and `commits` inside `config`. While `commits` is the same as with analyzeCommits, `nextRelease` contains a `type` (e.g. `'major'`) and the new version (e.g. `'1.0.0'`) and `lastRelease` contains the old `version`, the `gitHead` at the time of the release and the npm dist-`tag` (e.g. `'latest'`). Using this information you could [detect breaking changes](https://github.com/semantic-release/cracks) or hold back certain types of releases. Again: Be creative.
|
||
|
||
Passing an array of plugins will run them in series.
|
||
|
||
### `getLastRelease`
|
||
|
||
This plugin is responsible for determining a package’s last release version. The [default implementation](https://github.com/semantic-release/last-release-npm) uses the last published version on a npm registry.
|
||
|
||
### `generateNotes`
|
||
|
||
This plugin is responsible for generating release notes. Call the callback with the notes as a string. Have a look at the [default implementation](https://github.com/semantic-release/release-notes-generator/).
|
||
It receives a `commits` array, the `lastRelease` and `nextRelease` inside `config`.
|
||
|
||
### `publish`
|
||
|
||
This plugins is responsible for publishing the release. The default implementations publish on [npm](https://github.com/semantic-release/npm) and [github](https://github.com/semantic-release/github).
|
||
|
||
Passing an array of plugins will run them in series.
|
||
|
||
## ITYM*FAQ*LT
|
||
> I think you might frequently ask questions like these
|
||
|
||
### Why is the `package.json`’s version not updated in my repository?
|
||
|
||
The `npm` docs even state:
|
||
|
||
> The most important things in your package.json are the name and version fields. Those are actually required, and your package won’t install without them.
|
||
> – [npm docs](https://docs.npmjs.com/files/package.json#version)
|
||
|
||
While this entirely true the version number doesn’t have to be checked into source control. `semantic-release` takes care of the version field right before `npm publish` uses it – and this is the only point where it _really_ is required.
|
||
|
||
### Is there a way to preview which version would currently get published?
|
||
|
||
If you run `npm run semantic-release` locally a dry run gets performed, which logs the version that would currently get published.
|
||
|
||
### Can I run this on my own machine rather than on a CI server?
|
||
|
||
Of course you can, but this doesn’t necessarily mean you should. Running your tests on an independent machine before releasing software is a crucial part of this workflow. Also it is a pain to set this up locally, with tokens lying around and everything. That said, you can run the scripts with `--debug=false` explicitly. You have to export `GH_TOKEN=<your_token>` and `NPM_TOKEN=<your_other_token>`.
|
||
|
||
### Can I manually trigger the release of a specific version?
|
||
|
||
You can trigger a release by pushing to your GitHub repository. You deliberately cannot trigger a _specific_ version release, because this is the whole point of `semantic-release`. Start your packages with `1.0.0` and semver on.
|
||
|
||
### Is it _really_ a good idea to release on every push?
|
||
|
||
It is indeed a great idea because it _forces_ you to follow best practices. If you don’t feel comfortable making every passing feature or fix on your master branch addressable via `npm` you might not treat your master right. Have a look at [branch workflows](https://guides.github.com/introduction/flow/index.html). If you still think you should have control over the exact point in time of your release, e.g. because you are following a release schedule, you can release only on the `production`/`deploy`/`release` branch and push your code there in certain intervals, or better yet use [dist-tags](https://docs.npmjs.com/cli/dist-tag).
|
||
|
||
### Why should I trust `semantic-release` with my releases?
|
||
|
||
`semantic-release` has a full unit- and integration-test-suite that tests _actual_ `npm` publishes against the [npm-registry-couchapp](https://github.com/npm/npm-registry-couchapp/). A new version won’t get published if it doesn’t pass on all these engines.
|
||
|
||
### Why does `semantic-release` require node version >= 8
|
||
|
||
Being able to write code for just the most recent node versions greatly simplifies development. More language features are available, no transpilation is required, less test builds are to be run, awaited and debugged.
|
||
|
||
For a special purpose tool like `semantic-release`, that's only meant to be used in controlled CI environments, we think it's okay to have such a high version requirement. As `semantic-release` handles package publishing we expect almost every project to have at least one build job running node 8 already – and that's all it takes. Even if that's not that case `semantic-release` can still be executed with the help of [npx](https://www.npmjs.com/package/npx) (`npx -p node@8 npm run semantic-release`).
|
||
|
||
Please see our [Node Support Policy](#node-support-policy) for our long-term promise for supporting Node.
|
||
|
||
## Badge
|
||
|
||
Use this in one of your projects? Include one of these badges in your README.md to let people know that your package is published using `semantic-release`.
|
||
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
|
||
```md
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
```
|
||
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
|
||
```md
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
```
|
||
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
|
||
```md
|
||
[](https://github.com/semantic-release/semantic-release)
|
||
```
|
||
|
||
## Node Support Policy
|
||
|
||
We only support [Long-Term Support](https://github.com/nodejs/Release) versions of Node starting with [Node 8.9.0 (LTS)](https://nodejs.org/en/blog/release/v8.9.0/).
|
||
|
||
We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.
|
||
|
||
It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.
|
||
|
||
As each Node LTS version reaches its end-of-life we will remove that version from the node engines property of our package's package.json file. Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any merge requests or issues supporting an end-of-life version of Node will be closed.
|
||
|
||
We will accept code that allows this package to run on newer, non-LTS, versions of Node. Furthermore, we will attempt to ensure our own changes work on the latest version of Node. To help in that commitment, our continuous integration setup runs against all LTS versions of Node in addition the most recent Node release; called current.
|
||
|
||
JavaScript package managers should allow you to install this package with any version of Node, with, at most, a warning if your version of Node does not fall within the range specified by our node engines property. If you encounter issues installing this package, please report the issue to your package manager.
|
||
|
||
## License
|
||
|
||
MIT License
|
||
2015 © Stephan Bönnemann and [contributors](https://github.com/semantic-release/semantic-release/graphs/contributors)
|
||
|
||
[](https://twitter.com/trodrigues/status/509301317467373571)
|