Merge remote-tracking branch 'origin/beta'

.travis/node-versions.yml

@@ -1,4 +1,3 @@
 node_js:
   - 12
-  - 10
-  - 8.16
+  - 10.13

README.md

@@ -24,6 +24,9 @@
   <a href="https://www.npmjs.com/package/semantic-release">
     <img alt="npm next version" src="https://img.shields.io/npm/v/semantic-release/next.svg">
   </a>
+  <a href="https://www.npmjs.com/package/semantic-release">
+    <img alt="npm beta version" src="https://img.shields.io/npm/v/semantic-release/beta.svg">
+  </a>
 </p>
 
 **semantic-release** automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
@@ -39,6 +42,7 @@ This removes the immediate connection between human emotions and version numbers
 - New features and fixes are immediately available to users
 - Notify maintainers and users of new releases
 - Use formalized commit message convention to document changes in the codebase
+- Publish on different distribution channels (such as [npm dist-tags](https://docs.npmjs.com/cli/dist-tag)) based on git merges
 - Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
 - Avoid potential errors associated with manual releases
 - Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
@@ -68,11 +72,12 @@ Here is an example of the release type that will be done based on a commit messa
 
 ### Triggering a release
 
-For each new commits added to the release branch (i.e. `master`) 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.
+For each new commits 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.
 
-If you need more control over the timing of releases you have a couple of options:
-- Publish releases on a distribution channel (for example 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, and you can decide when to make an automatically released version available to the stable channel, and promote it.
-- Develop on a `dev` branch and merge it to the release branch (i.e. `master`) once you are ready to publish. **semantic-release** will run only on pushes to the release branch.
+**semantic-release** offers various ways to control the timing, the content and the audience of published releases. See example workflows in the following recipes:
+- [Using distribution channels](docs/recipes/distribution-channels.md#publishing-on-distribution-channels)
+- [Maintenance releases](docs/recipes/maintenance-releases.md#publishing-maintenance-releases)
+- [Pre-releases](docs/recipes/pre-releases.md#publishing-pre-releases)
 
 ### Release steps
 
@@ -90,6 +95,14 @@ After running the tests, the command `semantic-release` will execute the followi
 | Publish           | Publish the release.                                                                                                            |
 | Notify            | Notify of new releases or errors.                                                                                               |
 
+## Requirements
+
+In order to use **semantic-release** you need:
+- To host your code in a [Git repository](https://git-scm.com)
+- Use a Continuous Integration service that allows you to [securely set up credentials](docs/usage/ci-configuration.md#authentication)
+- Git CLI version [2.7.1 or higher](docs/support/FAQ.md#why-does-semantic-release-require-git-version--271) installed in your Continuous Integration environment
+- [Node.js](https://nodejs.org) version [8.16.0 or higher](docs/support/FAQ.md#why-does-semantic-release-require-node-version--816) installed in your Continuous Integration environment
+
 ## Documentation
 
 - Usage
@@ -98,14 +111,16 @@ After running the tests, the command `semantic-release` will execute the followi
   - [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
   - [Configuration](docs/usage/configuration.md#configuration)
   - [Plugins](docs/usage/plugins.md)
+  - [Workflow configuration](docs/usage/workflow-configuration.md)
   - [Shareable configurations](docs/usage/shareable-configurations.md)
 - Extending
   - [Plugins](docs/extending/plugins-list.md)
   - [Shareable configuration](docs/extending/shareable-configurations-list.md)
 - Recipes
-  - [CI configurations](docs/recipes/README.md#ci-configurations)
-  - [Git hosted services](docs/recipes/README.md#git-hosted-services)
-  - [Package managers and languages](docs/recipes/README.md#package-managers-and-languages)
+  - [CI configurations](docs/recipes/README.md)
+  - [Git hosted services](docs/recipes/README.md)
+  - [Release workflow](docs/recipes/README.md)
+  - [Package managers and languages](docs/recipes/README.md)
 - Developer guide
   - [JavaScript API](docs/developer-guide/js-api.md)
   - [Plugins development](docs/developer-guide/plugin.md)

SUMMARY.md

@@ -6,6 +6,7 @@
 - [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
 - [Configuration](docs/usage/configuration.md#configuration)
 - [Plugins](docs/usage/plugins.md)
+- [Workflow configuration](docs/usage/workflow-configuration.md)
 - [Shareable configurations](docs/usage/shareable-configurations.md)
 
 ## Extending

bin/semantic-release.js

@@ -10,7 +10,7 @@ var execa = require('execa');
 var findVersions = require('find-versions');
 var pkg = require('../package.json');
 
-var MIN_GIT_VERSION = '2.0.0';
+var MIN_GIT_VERSION = '2.7.1';
 
 if (!semver.satisfies(process.version, pkg.engines.node)) {
   console.error(
@@ -35,7 +35,7 @@ execa('git', ['--version'])
     process.exit(1);
   });
 
-// Node 8+ from this point on
+// Node 10+ from this point on
 require('../cli')()
   .then(exitCode => {
     process.exitCode = exitCode;

cli.js

@@ -19,7 +19,7 @@ module.exports = async () => {
 Usage:
   semantic-release [options] [plugins]`);
     })
-    .option('b', {alias: 'branch', describe: 'Git branch to release from', type: 'string', group: 'Options'})
+    .option('b', {alias: 'branches', describe: 'Git branches to release from', ...stringList, group: 'Options'})
     .option('r', {alias: 'repository-url', describe: 'Git repository URL', type: 'string', group: 'Options'})
     .option('t', {alias: 'tag-format', describe: 'Git tag format', type: 'string', group: 'Options'})
     .option('p', {alias: 'plugins', describe: 'Plugins', ...stringList, group: 'Options'})

docs/developer-guide/js-api.md

@@ -12,7 +12,14 @@ const stderrBuffer = WritableStreamBuffer();
 try {
   const result = await semanticRelease({
     // Core options
-    branch: 'master',
+    branches: [
+      '+([0-9])?(.{+([0-9]),x}).x',
+      'master',
+      'next',
+      'next-major',
+      {name: 'beta', prerelease: true},
+      {name: 'alpha', prerelease: true}
+    ],
     repositoryUrl: 'https://github.com/me/my-package.git',
     // Shareable config
     extends: 'my-shareable-config',
@@ -123,11 +130,12 @@ Type: `Object`
 
 Information related to the last release found:
 
-| Name    | Type     | Description                                                                                        |
-|---------|----------|----------------------------------------------------------------------------------------------------|
-| version | `String` | The version of the last release.                                                                   |
-| gitHead | `String` | The sha of the last commit being part of the last release.                                         |
-| gitTag  | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release. |
+| Name    | Type     | Description                                                                                                                         |
+|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------|
+| version | `String` | The version of the last release.                                                                                                    |
+| gitHead | `String` | The sha of the last commit being part of the last release.                                                                          |
+| gitTag  | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release.                                  |
+| channel | `String` | The distribution channel on which the last release was initially made available (`undefined` for the default distribution channel). |
 
 **Notes**: If no previous release is found, `lastRelease` will be an empty `Object`.
 
@@ -137,6 +145,7 @@ Example:
   gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
   version: '1.0.0',
   gitTag: 'v1.0.0',
+  channel: 'next'
 }
 ```
 
@@ -206,13 +215,14 @@ Type: `Object`
 
 Information related to the newly published release:
 
-| Name    | Type     | Description                                                                                       |
-|---------|----------|---------------------------------------------------------------------------------------------------|
-| type    | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`).               |
-| version | `String` | The version of the new release.                                                                   |
-| gitHead | `String` | The sha of the last commit being part of the new release.                                         |
-| gitTag  | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the new release. |
-| notes   | `String` | The release notes for the new release.                                                            |
+| Name    | Type     | Description                                                                                                                   |
+|---------|----------|-------------------------------------------------------------------------------------------------------------------------------|
+| type    | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`).                                           |
+| version | `String` | The version of the new release.                                                                                               |
+| gitHead | `String` | The sha of the last commit being part of the new release.                                                                     |
+| gitTag  | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the new release.                             |
+| notes   | `String` | The release notes for the new release.                                                                                        |
+| channel | `String` | The distribution channel on which the next release will be made available (`undefined` for the default distribution channel). |
 
 Example:
 ```js
@@ -222,26 +232,28 @@ Example:
   version: '1.1.0',
   gitTag: 'v1.1.0',
   notes: 'Release notes for version 1.1.0...',
+  channel : 'next'
 }
 ```
 
 #### releases
 
 Type: `Array<Object>`
 
-The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).<br>
+The list of releases published or made available to a distribution channel.<br>
 Each release object has the following properties:
 
-| Name       | Type     | Description                                                                                   |
-|------------|----------|-----------------------------------------------------------------------------------------------|
-| name       | `String` | **Optional.** The release name, only if set by the corresponding `publish` plugin.            |
-| url        | `String` | **Optional.** The release URL, only if set by the corresponding `publish` plugin.             |
-| type       | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`).           |
-| version    | `String` | The version of the release.                                                                   |
-| gitHead    | `String` | The sha of the last commit being part of the release.                                         |
-| gitTag     | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the release. |
-| notes      | `String` | The release notes for the release.                                                            |
-| pluginName | `String` | The name of the plugin that published the release.                                            |
+| Name       | Type     | Description                                                                                                    |
+|------------|----------|----------------------------------------------------------------------------------------------------------------|
+| name       | `String` | **Optional.** The release name, only if set by the corresponding `publish` plugin.                             |
+| url        | `String` | **Optional.** The release URL, only if set by the corresponding `publish` plugin.                              |
+| type       | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`).                            |
+| version    | `String` | The version of the release.                                                                                    |
+| gitHead    | `String` | The sha of the last commit being part of the release.                                                          |
+| gitTag     | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the release.                  |
+| notes      | `String` | The release notes for the release.                                                                             |
+| pluginName | `String` | The name of the plugin that published the release.                                                             |
+| channel    | `String` | The distribution channel on which the release is available (`undefined` for the default distribution channel). |
 
 Example:
 ```js
@@ -255,6 +267,7 @@ Example:
     gitTag: 'v1.1.0',
     notes: 'Release notes for version 1.1.0...',
     pluginName: '@semantic-release/github'
+    channel: 'next'
   },
   {
     name: 'npm package (@latest dist-tag)',
@@ -265,6 +278,7 @@ Example:
     gitTag: 'v1.1.0',
     notes: 'Release notes for version 1.1.0...',
     pluginName: '@semantic-release/npm'
+    channel: 'next'
    }
  ]
 ```

docs/recipes/README.md

@@ -9,4 +9,9 @@
 ## Git hosted services
 - [Git authentication with SSH keys](git-auth-ssh-keys.md)
 
+## Release workflow
+- [Publishing on distribution channels](distribution-channels.md)
+- [Publishing maintenance releases](maintenance-releases.md)
+- [Publishing pre-releases](pre-releases.md)
+
 ## Package managers and languages