docs: publish with gitbook
This commit is contained in:
Pierre Vanduynslager
@@ -0,0 +1,7 @@
|
||||
# Usage
|
||||
|
||||
- [Installation](installation.md#installation)
|
||||
- [CI Configuration](ci-configuration.md#ci-configuration)
|
||||
- [Configuration](configuration.md#configuration)
|
||||
- [Plugins](plugins.md)
|
||||
- [Shareable configurations](shareable-configurations.md)
|
||||
@@ -0,0 +1,37 @@
|
||||
# CI configuration
|
||||
|
||||
## Run `semantic-release` only after all tests succeeded
|
||||
|
||||
The `semantic-release` command must be executed only after all the tests in the CI build pass. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the `semantic-release` command is executed only after all jobs are successful. This can be achieved with [Travis Build Stages](https://docs.travis-ci.com/user/build-stages), [CircleCI Workflows](https://circleci.com/docs/2.0/workflows), [Codeship Deployment Pipelines](https://documentation.codeship.com/basic/builds-and-configuration/deployment-pipelines), [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html#introduction-to-pipelines-and-jobs), [Wercker Workflows](http://devcenter.wercker.com/docs/workflows), [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline) or specific tools like [`travis-deploy-once`](https://github.com/semantic-release/travis-deploy-once).
|
||||
|
||||
See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
|
||||
|
||||
## Authentication
|
||||
|
||||
Most **semantic-release** [plugins](plugins.md) require to set up authentication in order to publish to your package manager's registry or to access your project's Git hosted service. The authentication token/credentials have to be made available in the CI serice via environment variables.
|
||||
|
||||
See each plugin documentation for the environment variable to set up.
|
||||
|
||||
The default [npm](https://github.com/semantic-release/npm#environment-variables) and [github](https://github.com/semantic-release/github#environment-variables) plugins require the following environment variables:
|
||||
|
||||
| Variable | Description |
|
||||
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `NPM_TOKEN` | npm token created via [npm token create](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens).<br/>**Note**: Only the `auth-only` [level of npm two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported. |
|
||||
| `GH_TOKEN` | GitHub authentication token.<br/>**Note**: Only the [personal token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) authentication is supported. |
|
||||
|
||||
See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
|
||||
|
||||
## Automatic setup with `semantic-release-cli`
|
||||
|
||||
[`semantic-release-cli`](https://github.com/semantic-release/cli) allow to easily [install](installation.md) **semantic-release** in your Node project and set up the CI configuration:
|
||||
|
||||
```bash
|
||||
npm install -g semantic-release-cli
|
||||
|
||||
cd your-module
|
||||
semantic-release-cli setup
|
||||
```
|
||||
|
||||
|
||||
|
||||
See the [semantic-release-cli](https://github.com/semantic-release/cli#what-it-does) documentation for more details.
|
||||
@@ -0,0 +1,168 @@
|
||||
# Configuration
|
||||
|
||||
In order to customize **semantic-release**’s behavior, [options](#options) and [plugins](plugins.md) can be set via:
|
||||
- A `.releaserc` file, written in YAML or JSON, with optional extensions: .`yaml`/`.yml`/`.json`/`.js`
|
||||
- A `release.config.js` file that exports an object
|
||||
- A `release` key in the project's `package.json` file
|
||||
- CLI arguments
|
||||
|
||||
The following two examples are the same.
|
||||
|
||||
Via CLI argument:
|
||||
|
||||
```bash
|
||||
$ semantic-release --branch next
|
||||
```
|
||||
|
||||
Via `release` key in the project's `package.json` file:
|
||||
|
||||
```json
|
||||
"release": {
|
||||
"branch": "next"
|
||||
}
|
||||
```
|
||||
```bash
|
||||
$ semantic-release
|
||||
```
|
||||
|
||||
**Note**: CLI arguments take precedence over options configured in the configuration file.
|
||||
|
||||
**Note**: Plugins options cannot be defined via CLI arguments and must be defined in the configuration file.
|
||||
|
||||
## Options
|
||||
|
||||
### extends
|
||||
|
||||
Type: `Array`, `String`
|
||||
|
||||
CLI arguments: `-e`, `--extends`
|
||||
|
||||
List of modules or file paths containing a [shareable configuration](shareable-configurations.md). If multiple shareable configuration are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration.
|
||||
|
||||
**Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.
|
||||
|
||||
### branch
|
||||
|
||||
Type: `String`
|
||||
|
||||
Default: `master`
|
||||
|
||||
CLI arguments: `-b`, `--branch`
|
||||
|
||||
The branch on which releases should happen.
|
||||
|
||||
### repositoryUrl
|
||||
|
||||
Type: `String`
|
||||
|
||||
Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
|
||||
|
||||
CLI arguments: `-r`, `--repository-url`
|
||||
|
||||
The git repository URL
|
||||
|
||||
Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)).
|
||||
|
||||
**Note**: 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.**
|
||||
|
||||
### dryRun
|
||||
|
||||
Type: `Boolean`
|
||||
|
||||
Default: `false` if running in a CI environment, `false` otherwise
|
||||
|
||||
CLI arguments: `-d`, `--dry-run`
|
||||
|
||||
Dry-run mode, skip publishing, print next version and release notes.
|
||||
|
||||
### noCi
|
||||
|
||||
Type: `Boolean`
|
||||
|
||||
Default: `false`
|
||||
|
||||
CLI arguments: `--no-ci`
|
||||
|
||||
Skip Continuous Integration environment verifications, allowing to make releases from a local machine.
|
||||
|
||||
### debug
|
||||
|
||||
Type: `Boolean`
|
||||
|
||||
Default: `false`
|
||||
|
||||
CLI argument: `--debug`
|
||||
|
||||
Output debugging information. It can also be enabled by set the `DEBUG` environment variable to `semantic-release`.
|
||||
|
||||
### verifyConditions
|
||||
|
||||
Type: `Array`, `String`, `Object`
|
||||
|
||||
Default: `['@semantic-release/npm', '@semantic-release/github']`
|
||||
|
||||
CLI argument: `--verify-conditions`
|
||||
|
||||
Define the list of [verify conditions plugins](plugins.md#verifyconditions-plugin). Plugins will run in series, in the order defined in the `Array`.
|
||||
|
||||
See [Plugins configuration](plugins.md#configuration) for more details.
|
||||
|
||||
### getLastRelease
|
||||
|
||||
Type: `String`, `Object`
|
||||
|
||||
Default: `['@semantic-release/npm']`
|
||||
|
||||
CLI argument: `--get-last-release`
|
||||
|
||||
Define the [get last release plugin](plugins.md#getlastrelease-plugin).
|
||||
|
||||
See [Plugins configuration](plugins.md#configuration) for more details.
|
||||
|
||||
### analyzeCommits
|
||||
|
||||
Type: `String`, `Object`
|
||||
|
||||
Default: `['@semantic-release/commit-analyzer']`
|
||||
|
||||
CLI argument: `--analyze-commits`
|
||||
|
||||
Define the [analyze commits plugin](plugins.md#analyzecommits-plugin).
|
||||
|
||||
See [Plugins configuration](plugins.md#configuration) for more details.
|
||||
|
||||
### verifyRelease
|
||||
|
||||
Type: `Array`, `String`, `Object`
|
||||
|
||||
Default: `[]`
|
||||
|
||||
CLI argument: `--verify-release`
|
||||
|
||||
Define the list of [verify release plugins](plugins.md#verifyrelease-plugin). Plugins will run in series, in the order defined in the `Array`.
|
||||
|
||||
See [Plugins configuration](plugins.md#configuration) for more details.
|
||||
|
||||
### generateNotes
|
||||
|
||||
Type: `String`, `Object`
|
||||
|
||||
Default: `['@semantic-release/release-notes-generator']`
|
||||
|
||||
CLI argument: `--generate-notes`
|
||||
|
||||
Define the [generate notes plugin](plugins.md#generatenotes-plugin).
|
||||
|
||||
See [Plugins configuration](plugins.md#configuration) for more details.
|
||||
|
||||
### publish
|
||||
|
||||
Type: `Array`, `String`, `Object`
|
||||
|
||||
Default: `['@semantic-release/npm', '@semantic-release/github']`
|
||||
|
||||
CLI argument: `--publish`
|
||||
|
||||
Define the list of [publish plugins](plugins.md#publish-plugin). Plugins will run in series, in the order defined in the `Array`.
|
||||
|
||||
See [Plugins configuration](plugins.md#configuration) for more details.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Installation
|
||||
|
||||
## Local installation
|
||||
|
||||
For [Node modules projects](https://docs.npmjs.com/getting-started/creating-node-modules) we recommend to install **semantic-release** locally and to run the `semantic-release` command with a [npm script](https://docs.npmjs.com/misc/scripts):
|
||||
|
||||
```bash
|
||||
$ npm install --save-dev semantic-release
|
||||
```
|
||||
|
||||
In your `package.json`:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"semantic-release": "semantic-release"
|
||||
}
|
||||
```
|
||||
|
||||
Then in the CI environment:
|
||||
|
||||
```bash
|
||||
$ npm run semantic-release
|
||||
```
|
||||
|
||||
## Global installation
|
||||
|
||||
For other type of projects we recommend to install **semantic-release** globally directly in the CI environment:
|
||||
|
||||
```bash
|
||||
$ npm install -g semantic-release
|
||||
$ semantic-release
|
||||
```
|
||||
@@ -0,0 +1,82 @@
|
||||
# Plugins
|
||||
|
||||
Each [release steps](../../README.md#release-steps) is implemented within a plugin or a list of plugins that can be configured, allowing to support different [commit message format](../../README.md#commit-message-format), release not generator and publishing platforms.
|
||||
|
||||
## Plugin types
|
||||
|
||||
### verifyConditions plugin
|
||||
|
||||
Plugin responsible for verifying all the conditions to proceed with the release: configuration is correct, authentication token are valid, etc...
|
||||
|
||||
Default implementation: [npm](https://github.com/semantic-release/npm#verifyconditions) and [github](https://github.com/semantic-release/github#verifyconditions).
|
||||
|
||||
### getLastRelease plugin
|
||||
|
||||
Plugin responsible for determining the version of the package last release.
|
||||
|
||||
Default implementation: [@semantic-release/npm](https://github.com/semantic-release/npm#getlastrelease).
|
||||
|
||||
### analyzeCommits plugin
|
||||
|
||||
Plugin responsible for determining the type of the next release (`major`, `minor` or `patch`).
|
||||
|
||||
Default implementation: [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer).
|
||||
|
||||
### verifyRelease plugin
|
||||
|
||||
Plugin responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published match certain expectations. For example the [cracks plugin](https://github.com/semantic-release/cracks) allows to verify that if a release contains breaking changes, its type must be `major`.
|
||||
|
||||
Default implementation: none.
|
||||
|
||||
### generateNotes plugin
|
||||
|
||||
Plugin responsible for generating release notes.
|
||||
|
||||
Default implementation: [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator).
|
||||
|
||||
### publish plugin
|
||||
|
||||
Plugin responsible for publishing the release.
|
||||
|
||||
Default implementation: [npm](https://github.com/semantic-release/npm#publish) and [github](https://github.com/semantic-release/github#publish).
|
||||
|
||||
## Configuration
|
||||
|
||||
Plugin can be configured by specifying the plugin's module name or file path directly as a `String` or within the `path` key of an `Object`.
|
||||
|
||||
Plugins specific options can be set similarly to the other **semantic-release** [options](configuration.md#options) or within the plugin `Object`. Plugins options defined along the other **semantic-release** [options](configuration.md#options) will apply to all plugins, while the one defined within the plugin `Object` will apply only to this specific plugin.
|
||||
|
||||
For example:
|
||||
```json
|
||||
{
|
||||
"release": {
|
||||
"verifyConditions": [
|
||||
{
|
||||
"path": "@semantic-release/exec",
|
||||
"cmd": "verify-conditions.sh"
|
||||
},
|
||||
"@semantic-release/npm",
|
||||
"@semantic-release/github"
|
||||
],
|
||||
"analyzeCommits": "custom-plugin",
|
||||
"verifyRelease": [
|
||||
{
|
||||
"path": "@semantic-release/exec",
|
||||
"cmd": "verify-release.sh"
|
||||
},
|
||||
],
|
||||
"generateNotes": "./build/my-plugin.js",
|
||||
"githubUrl": "https://my-ghe.com",
|
||||
"githubApiPathPrefix": "/api-prefix"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With this configuration:
|
||||
- the `custom-plugin` npm module will be used to [analyze commits](#analyzecommits-plugin)
|
||||
- the `./build/my-plugin.js` script will be used to [generate release notes](#generatenotes-plugin)
|
||||
- the [`@semantic-release/exec`](https://github.com/semantic-release/exec), [`@semantic-release/npm`](https://github.com/semantic-release/npm) and [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugins will be used to [verify conditions](#verifyconditions-plugin)
|
||||
- the [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin will be used to [verify the release](#verifyrelease-plugin)
|
||||
- the `cmd` option will be set to `verify-conditions.sh` only for the [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin used to [verify conditions](#verifyconditions-plugin)
|
||||
- the `cmd` option will be set to `verify-release.sh` only for the [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin used to [verify the release](#verifyrelease-plugin)
|
||||
- the `githubUrl` and `githubApiPathPrefix` options will be set to respectively `https://my-ghe.com` and `/api-prefix` for all plugins
|
||||
@@ -0,0 +1,5 @@
|
||||
# Shareable configurations
|
||||
|
||||
A sharable configuration is an [npm](https://www.npmjs.com/) package that exports a **semantic-release** configuration object. It allows to easily use the same configuration across several projects.
|
||||
|
||||
The shareable configurations to use can be set with the [extends](configuration.md#extends) option.
|
||||
Reference in New Issue
Block a user