simon/semantic-release
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: support multiple branches and distribution channels

Browse Source 
- Allow to configure multiple branches to release from
- Allow to define a distribution channel associated with each branch
- Manage the availability on distribution channels based on git merges
- Support regular releases, maintenance releases and pre-releases
- Add the `addChannel` plugin step to make an existing release available on a different distribution channel

BREAKING CHANGE: the `branch` option has been removed in favor of `branches`

The new `branches` option expect either an Array or a single branch definition. To migrate your configuration:
- If you want to publish package from multiple branches, please the configuration documentation
- If you use the default configuration and want to publish only from `master`: nothing to change
- If you use the `branch` configuration and want to publish only from one branch: replace `branch` by `branches` (`"branch": "my-release-branch"` => `"branches": "my-release-branch"`)
This commit is contained in:
Pierre Vanduynslager
2018-11-29 14:13:03 -05:00
parent 7a9922a492
commit 7b4052470b
50 changed files with 4069 additions and 516 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/developer-guide/js-api.md
+30 -23
View File
@@ -123,11 +123,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 +138,7 @@ Example:
gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
version: '1.0.0',
gitTag: 'v1.0.0',
channel: 'next'
}
```
@@ -206,13 +208,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,6 +225,7 @@ Example:
version: '1.1.0',
gitTag: 'v1.1.0',
notes: 'Release notes for version 1.1.0...',
channel : 'next'
}
```
@@ -229,19 +233,20 @@ Example:
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 +260,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 +271,7 @@ Example:
gitTag: 'v1.1.0',
notes: 'Release notes for version 1.1.0...',
pluginName: '@semantic-release/npm'
channel: 'next'
}
]
```
docs/recipes/README.md
+5
View File
@@ -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
docs/recipes/distribution-channels.md
+116
View File
@@ -0,0 +1,116 @@
# Publishing on distribution channels
This recipe will walk you through a simple example that uses distribution channels to make releases available only to a subset of users, in order to collect feedbacks before distributing the release to all users.
This example uses the **semantic-release** default configuration:
- [branches](../usage/configuration.md#branches): `['+([1-9])?(.{+([1-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
- [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
## Initial release
We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
The Git history of the repository is:
```
* feat: initial commit # => v1.0.0 on @latest
```
## Releasing a bug fix
We can now continue to commit changes and release updates to our users. For example we can commit a bug fix with the message `fix: a fix` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
```
## Releasing a feature on next
We now want to develop an important feature, which is a breaking change. Considering the scope of this feature we want to make it available, at first, only to our most dedicated users in order to get feedback. Once we get that feedback we can make improvements and ultimately make the new feature available to all users.
To implement that workflow we can create the branch `next` and commit our feature to this branch. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@next`. That means only the users installing our module with `npm install example-module@next` will receive the version `2.0.0`. Other users installing with `npm install example-module` will still receive the version `1.0.1`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
```
## Releasing a bug fix on next
One of our users starts to use the new `2.0.0` release and reports a bug. We develop a bug fix and commit it to the `next` branch with the message `fix: fix something on the big feature`. When pushing that commit, **semantic-release** will release the version `2.0.1` on the dist-tag `@next`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
| * fix: fix something on the big feature # => v2.0.1 on @next
```
## Releasing a feature on latest
We now want to develop a smaller, non-breaking feature. Its scope is small enough that we don't need to have a phase of feedback and we can release it to all users right away.
If we were to commit that feature on `next` only a subset of users would get it, and we would need to wait for the end of our feedback period in order to make both the big and the small feature available to all users.
Instead, we develop that small feature commit it to `master` with the message `feat: a small feature`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@latest` so all users can benefit from it right away.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
| * fix: fix something on the big feature # => v2.0.1 on @next
* | feat: a small feature # => v1.1.0 on @latest
```
## Porting a feature to next
Most of our users now have access to the small feature, but we still need to make it available to our users using the `@next` dist-tag. To do so we need to merge our changes made on `master` (the commit `feat: a small feature`) into `next`. As `master` and `next` branches have diverged, this merge might require to resolve conflicts.
Once the conflicts are resolved and the merge commit is pushed to `next`, **semantic-release** will release the version `2.1.0` on the dist-tag `@next` which contains both our small and big feature.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
| * fix: fix something on the big feature # => v2.0.1 on @next
* | feat: a small feature # => v1.1.0 on @latest
| * Merge branch master into next # => v2.1.0 on @next
```
## Adding a version to latest
After a period of feedback from our users using the `@next` dist-tag we feel confident to make our big feature available to all users. To do so we merge the `next` branch into `master`. There should be no conflict as `next` is strictly ahead of `master`.
Once the merge commit is pushed to `next`, **semantic-release** will add the version `2.1.0` to the dist-tag `@latest` so all users will receive it when installing out module with `npm install example-module`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
| * fix: fix something on the big feature # => v2.0.1 on @next
* | feat: a small feature # => v1.1.0 on @latest
| * Merge branch master into next # => v2.1.0 on @next
| /|
* | Merge branch next into master # => v2.1.0 on @latest
```
We can now continue to push new fixes and features on `master`, or a new breaking change on `next` as we did before.
docs/recipes/maintenance-releases.md
+156
View File
@@ -0,0 +1,156 @@
# Publishing maintenance releases
This recipe will walk you through a simple example that uses Git branches and distribution channels to publish fixes and features for old versions of a package.
This example uses the **semantic-release** default configuration:
- [branches](../usage/configuration.md#branches): `['+([1-9])?(.{+([1-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
- [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
## Initial release
We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit`. When pushing that commit, on `master` **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
The Git history of the repository is:
```
* feat: initial commit # => v1.0.0 on @latest
```
## Releasing a breaking change
We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change.
We commit that change with the message `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required` to `master`. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
* feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
```
## Releasing a feature for version 1.x users
One of our users request a new feature, however they cannot migrate to Node.js 8 or higher due to corporate policies.
If we were to push that feature on `master` and release it, the new version would require Node.js 8 or higher as the release would also contains the commit `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
Instead, we create the branch `1.x` from the tag `v1.0.0` with the command `git checkout -b 1.x v1.0.0` and we commit that feature with the message `feat: a feature` to the branch `1.x`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@release-1.x` so users who can't migrate to Node.js 8 or higher can benefit from it.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
| * feat: a feature # => v1.1.0 on @1.x
```
## Releasing a bug fix for version 1.0.x users
Another user currently using version `1.0.0` reports a bug. They cannot migrate to Node.js 8 or higher and they also cannot migrate to `1.1.0` as they do not use the feature developed in `feat: a feature` and their corporate policies require to go through a costly quality insurance process for each `minor` upgrades.
In order to deliver the bug fix in a `patch` release, we create the branch `1.0.x` from the tag `v1.0.0` with the command `git checkout -b 1.0.x v1.0.0` and we commit that fix with the message `fix: a fix` to the branch `1.0.x`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@release-1.0.x` so users who can't migrate to `1.1.x` or `2.x` can benefit from it.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
| | \
| * | feat: a feature # => v1.1.0 on @1.x
| | * fix: a fix # => v1.0.1 on @1.0.x
```
## Porting a bug fix from 1.0.x to 1.x
Now that we have released a fix in version `1.0.1` we want to make it available to `1.1.x` users as well.
To do so we need to merge the changes made on `1.0.x` (the commit `fix: a fix`) into the `1.x` branch. As `1.0.x` and `1.x` branches have diverged, this merge might require to resolve conflicts.
Once the conflicts are resolved and the merge commit is pushed to the branch `1.x`, **semantic-release** will release the version `1.1.1` on the dist-tag `@release-1.x` which contains both our feature and bug fix.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
| | \
| * | feat: a feature # => v1.1.0 on @1.x
| | * fix: a fix # => v1.0.1 on @1.0.x
| | /|
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
```
## Porting bug fixes and features to master
Finally we want to make both our feature and bug fix available to users using the `@latest` dist-tag.
To do so we need to merge the changes made on `1.x` (the commits `feat: a feature` and `fix: a fix`) into `master`. As `1.x` and `master` branches have diverged, this merge might require to resolve conflicts.
Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `2.1.0` on the dist-tag `@latest` which now contains the breaking change feature, the feature and the bug fix.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
| | \
| * | feat: a feature # => v1.1.0 on @1.x
| | * fix: a fix # => v1.0.1 on @1.0.x
| | /|
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
| /| |
* | | Merge branch 1.x into master # => v2.1.0 on @latest
```
## Releasing a bug fix for version 2.1.0 users
One of our users using the version `2.1.0` version reports a bug.
We can simply commit the bug fix with the message `fix: another fix` to `master`. When pushing that commit, **semantic-release** will release the version `2.1.1` on the dist-tag `@latest`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
| | \
| * | feat: a feature # => v1.1.0 on @1.x
| | * fix: a fix # => v1.0.1 on @1.0.x
| | /|
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
| /| |
* | | Merge branch 1.x into master # => v2.1.0 on @latest
* | | fix: another fix # => v2.1.1 on @latest
```
## Porting a bug fix from master to 1.x
The bug fix `fix: another fix` also affects version `1.1.1` users, so we want to port it to the `1.x` branch.
To do so we need to cherry pick our fix commit made on `master` (`fix: another fix`) into `1.x` with `git checkout 1.x && git cherry-pick <sha of fix: another fix>`. As `master` and `1.x` branches have diverged, the cherry picking might require to resolve conflicts.
Once the conflicts are resolved and the commit is pushed to `1.x`, **semantic-release** will release the version `1.1.2` on the dist-tag `@release-1.x` which contains `feat: a feature`, `fix: a fix` and `fix: another fix` but not `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
| | \
| * | feat: a feature # => v1.1.0 on @1.x
| | * fix: a fix # => v1.0.1 on @1.0.x
| | /|
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
| /| |
* | | Merge branch 1.x into master # => v2.1.0 on @latest
* | | fix: another fix # => v2.1.1 on @latest
| | |
| * | fix: another fix # => v1.1.2 on @1.x
```
docs/recipes/pre-releases.md
+196
View File
@@ -0,0 +1,196 @@
# Publishing pre-releases
This recipe will walk you through a simple example that uses pre-releases to publish beta versions while working on a future major release and then make only one release on the default distribution.
This example uses the **semantic-release** default configuration:
- [branches](../usage/configuration.md#branches): `['+([1-9])?(.{+([1-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
- [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
## Initial release
We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit`. When pushing that commit, on `master` **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
The Git history of the repository is:
```
* feat: initial commit # => v1.0.0 on @latest
```
## Working on a future release
We now decide to work on a future major release, which will be composed of multiple features, some of them being breaking changes. We want to publish our package for each new feature developed for test purpose, however we do not want to increment our package version or make it available to our users until all the features are developed and tested.
To implement that workflow we can create the branch `beta` and commit our first feature there. When pushing that commit, **semantic-release** will publish the pre-release version `2.0.0-beta.1` on the dist-tag `@beta`. That allow us to run integration tests by installing our module with `npm install example-module@beta`. Other users installing with `npm install example-module` will still receive the version `1.0.0`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
```
We can continue to work on our future release by committing and pushing other features or bug fixes on the `beta` branch. With each push, **semantic-release** will publish a new pre-release on the dist-tag `@beta`, which allow us to run our integration tests.
With another feature, the Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
```
## Releasing a bug fix on the default distribution channel
In the meantime we can also continue to commit changes and release updates to our users.
For example, we can commit a bug fix with the message `fix: a fix` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
```
## Working on another future release
We now decide to work on another future major release, in parallel of the beta one, which will also be composed of multiple features, some of them being breaking changes.
To implement that workflow we can create the branch `alpha` from the branch `beta` and commit our first feature there. When pushing that commit, **semantic-release** will publish the pre-release version `3.0.0-alpha.1` on the dist-tag `@alpha`. That allow us to run integration tests by installing our module with `npm install example-module@alpha`. Other users installing with `npm install example-module` will still receive the version `1.0.0`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
| | \
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
```
We can continue to work on our future release by committing and pushing other features or bug fixes on the `alpha` branch. With each push, **semantic-release** will publish a new pre-release on the dist-tag `@alpha`, which allow us to run our integration tests.
With another feature, the Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
| | \
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
```
## Publishing the 2.0.0 beta release to the default distribution channel
Once we've developed and pushed all the feature we want to include in the future version `2.0.0` in the `beta` branch and all our tests are successful we can release it to our users.
To do so we need to merge our changes made on `beta` into `master`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
| | \
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /| |
* | | Merge branch beta into master # => v2.0.0 on @latest
```
## Publishing the 3.0.0 alpha release to the beta distribution channel
Now that we published our the version `2.0.0` that was previously in beta, we decide to promote the version `3.0.0` in alpha to beta.
To do so we need to merge our changes made on `alpha` into `beta`. There should be no conflict as `alpha` is strictly ahead of `master`.
Once the merge commit is pushed to `beta`, **semantic-release** will publish the pre-release version `3.0.0-beta.1` on the dist-tag `@beta`, which allow us to run our integration tests.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
| | \
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /| |
* | | Merge branch beta into master # => v2.0.0 on @latest
| | /|
| * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
```
## Publishing the 3.0.0 beta release to the default distribution channel
Once we've developed and pushed all the feature we want to include in the future version `3.0.0` in the `beta` branch and all our tests are successful we can release it to our users.
To do so we need to merge our changes made on `beta` into `master`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `3.0.0` on the dist-tag `@latest`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
| | \
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /| |
* | | Merge branch beta into master # => v2.0.0 on @latest
| | /|
| * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
| /| |
* | | Merge branch beta into master # => v3.0.0 on @latest
```
## Working on a third future release
We can now start to work on a new future major release, version `4.0.0`, on the `@beta` distribution channel.
To do so we fist need to update the `beta` branch with all the changes from `master` (the commits `fix: a fix`). As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
We can now commit our new feature on `beta`. When pushing that commit, **semantic-release** will publish the pre-release version `3.1.0-beta.1` on the dist-tag `@beta`. That allow us to run integration tests by installing our module with `npm install example-module@beta`. Other users installing with `npm install example-module` will still receive the version `3.0.0`.
The Git history of the repository is now:
```
* feat: initial commit # => v1.0.0 on @latest
| \
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
| * feat: second feature # => v2.0.0-beta.2 on @beta
* | fix: a fix # => v1.0.1 on @latest
| | \
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /| |
* | | Merge branch beta into master # => v2.0.0 on @latest
| | /|
| * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
| /| |
* | | Merge branch beta into master # => v3.0.0 on @latest
| \| |
| * | Merge branch master into beta
| * | feat: new feature # => v3.1.0-beta.1 on @beta
```
docs/usage/configuration.md
+19 -9
View File
@@ -1,7 +1,7 @@
# Configuration
**semantic-release** configuration consists of:
- Git repository options ([URL](#repositoryurl), [release branch](#branch) and [tag format](#tagformat))
- Git repository options ([URL](#repositoryurl), [release branches](#branches) and [tag format](#tagformat))
- [plugins](#plugins) definition
- run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
@@ -25,7 +25,7 @@ Via `release` key in the project's `package.json` file:
```json
{
"release": {
"branch": "next"
"branches": ["master", "next"]
}
}
```
@@ -37,7 +37,7 @@ Via `.releaserc` file:
```json
{
"branch": "next"
"branches": ["master", "next"]
}
```
```bash
@@ -67,13 +67,23 @@ List of modules or file paths containing a [shareable configuration](shareable-c
**Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.
### branch
### branches
Type: `String`<br>
Default: `master`<br>
CLI arguments: `-b`, `--branch`
Type: `Array`, `String`, `Object`<br>
Default: `['+([1-9])?(.{+([1-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`<br>
CLI arguments: `--branches`
The branch on which releases should happen.
The branches on which releases should happen. By default **semantic-release** will release:
- regular releases to the default distribution channel from the branch `master`
- regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a number)
- regular releases to the `next` distribution channel from the branch `next` if it exists
- regular releases to the `next-major` distribution channel from the branch `next-major` if it exists
- prereleases to the `beta` distribution channel from the branch `beta` if it exists
- prereleases to the `alpha` distribution channel from the branch `alpha` if it exists
**Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://help.github.com/articles/about-protected-branches).
See [Plugins configuration](plugins.md#plugins) for more details.
### repositoryUrl
@@ -144,7 +154,7 @@ Output debugging information. This can also be enabled by setting the `DEBUG` en
## Existing version tags
**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the [release branch](#branch) history and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`).
**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the [release branches](#branches) history and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`).
If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case.
docs/usage/workflow-configuration.md
+187
View File
@@ -0,0 +1,187 @@
# Workflow configuration
**semantic-release** allow to manage and automate complex release workflow, based on multiple Git branches and distribution channels. This allow to:
- Distributes certain releases to a particular group of users via distribution channels
- Manage the availability of releases on distribution channels via branches merge
- Maintain multiple lines of releases in parrallel
- Work on large future releases outside the normal flow of one version increment per Git push
See [Release workflow recipes](../recipes/README.md#release-workflow) for detailed examples.
The release workflow is configured via the [branches option](./configuration.md#branches) which accepts a single or an array of branch definitions.
Each branch can be defined either as a string, a [glob](https://github.com/micromatch/micromatch#matching-features) or an object. For string and glob definitions each [property](#branches-properties) will be defaulted.
A branch can defined as one of three types:
- [release](#release-branches): to make releases on top of the last version released
- [maintenance](#maintenance-branches): to make release on top of an old release
- [pre-release](#pre-release-branches): to make pre-releases
The type of the branch is automatically determined based on naming convention and/or [properties](#branches-properties).
## Branches properties
| Property | Branch type | Description | Default |
|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| `name` | All | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](#name). | - The value itself if defined as a `String` or the matching branches name if defined as a glob. |
| `channel` | All | The distribution channel on which to publish releases from this branch. See [channel](#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones. |
| `range` | [maintenance](#maintenance-branches) only | **Required unless `name` is formatted like `N.N.x` or `N.x` (`N` is a number).** The range of [semantic versions](https://semver.org) to support on this branch. See [range](#range). | The value of `name`. |
| `prerelease` | [pre-release](#pre-release-branches) only | **Required.** The pre-release detonation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](#prerelease). | - |
### name
A `name` is required for any type of branch.
It can be defined as a [glob](https://github.com/micromatch/micromatch#matching-features) in which case the definition will be expanded to one per matching branch existing in the repository.
If `name` doesn't match to any branch existing in the repository, the definition will be ignored. For example the default configuration includes the definition `next` and `next-major` which will become active only when the branches `next` and/or `next-major` are created in the repository. This allow to define your workflow once with all potential branches you might use and have the effective configuration evolving as you create new branches.
For example the configuration `['+([1-9])?(.{+([1-9]),x}).x', 'master', 'next']` will be expanded as:
```js
{
branches: [
{name: '1.x', range: '1.x', channel: '1.x'}, // Only after the `1.x` is created in the repo
{name: '2.x', range: '2.x', channel: '2.x'}, // Only after the `2.x` is created in the repo
{name: 'master'},
{name: 'next', channel: 'next'}, // Only after the `next` is created in the repo
]
}
```
### channel
The `channel` can be defined for any branch type. If it's not defined, releases will be done on the default distribution channel (for example the `@latest` [dist-tag](https://docs.npmjs.com/cli/dist-tag) for npm).
The value of `channel`, if defined, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available.
For example the configuration `['master', {name: 'next', channel: 'channel-${name}'}]` will be expanded as:
```js
{
branches: [
{name: 'master'}, // `channel` is undefined so the default distribution channel will be used
{name: 'next', channel: 'channel-next'}, // `channel` is built with the template `channel-${name}`
]
}
```
### range
A `range` only applies to maintenance branches, is required and must be formatted like `N.N.x` or `N.x` (`N` is a number). In case the `name` is formatted as a range (for example `1.x` or `1.5.x`) the branch will be considered a maintenance branch and the `name` value will be used for the `range`.
For example the configuration `['1.1.x', '1.2.x', 'master']` will be expanded as:
```js
{
branches: [
{name: '1.1.x', range: '1.1.x', channel: '1.1.x'},
{name: '1.2.x', range: '1.2.x', channel: '1.2.x'},
{name: 'master'},
]
}
```
### prerelease
A `prerelease` property applies only to pre-release branches, is required and The `prerelease` value must be valid per the [Semantic Versioning Specification](https://semver.org/#spec-item-9). It will determine the name of versions (for example if `prerelease` is set to `beta` the version be formatted like `2.0.0-beta.1`, `2.0.0-beta.2` etc...).
If the `prerelease` property is set to `true` the `name` value will be used.
The value of `prerelease`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available.
For example the configuration `['master', {name: 'pre/rc', prerelease: '${name.replace(/^pre\\//g, "")}'}, {name: 'beta', prerelease: true}]` will be expanded as:
```js
{
branches: [
{name: 'master'},
{name: 'pre/rc', channel: 'pre/rc', prerelease: 'rc'}, // `prerelease` is built with the template `${name.replace(/^pre\\//g, "")}`
{name: 'beta', channel: 'beta', prerelease: 'beta'}, // `prerelease` is set to `beta` as it is the value of `name`
]
}
```
## Branch types
### Release branches
A release branch is the base type of branch used by **semantic-release** that allows to publish releases with a [semantic version](https://semver.org), optionally on a specific distribution channel. Distribution channels (for example [npm dist-tags](https://docs.npmjs.com/cli/dist-tag) or [Chrome release channels](https://www.chromium.org/getting-involved/dev-channel)) are a way to distribute new releases only to a subset of users in order to get early feedback. Later on those releases can be added to the general distribution channel to be made available to all users.
**semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release branch to another](#merging-into-a-release-branch).
A project must define a minimum of 1 release branch and can have a maximum of 3. The order of the release branch definitions is significant, as versions released on a given branch must always be higher than the last release made on the previous branch. This allow to avoid situation that would lead to an attempt to publish releases with the same version number but different codebase. When multiple release branches are configured and a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them.
**Note:** With **semantic-release** as with most package managers, a release version must be unique, independently of the distribution channel on which it is available.
See [publishing on distribution channels recipe](../recipes/distribution-channels.md) for a detailed example.
#### Pushing to a release branch
With the configuration `"branches": ["master", "next"]`, if the last release published from `master` is `1.0.0` then:
- Only versions in range `1.x.x` can be published from `master`, so only `fix` and `feat` commits can be pushed to `master`
- Only versions in range `>=2.0.0` release can be published from `next`, so a `BREAKING CHANGE` commit must be pushed first on `next` and can be followed by any type of commits
With the configuration `"branches": ["master", "next", "next-major"]`, if the last release published from `master` is `1.0.0` then:
- Only versions in range `1.0.x` can be published from `master`, so only `fix` commits can be pushed to `master`
- Only versions in range `>=1.1.0` can be published from `next`, so a `feat` commit must be pushed first on `next` and can be followed by `fix` and `feat` commits
- Only versions in range `>=2.0.0` release can be published from `next`, so a `BREAKING CHANGE` commit must be pushed first on `next-major` and can be followed by any type of commits
Those verifications prevent situations such as:
1. Create a `feat` commit on `next` which triggers the release of version `1.0.0` on channel `next`
2. Merge `next` into `master` which adds `1.0.0` on the default channel
3. Push a `fix` commit to `master` which triggers the release of version `1.0.1` on the default channel
4. Push a `fix` commit to `next` which would attempt to release the version `1.0.1` on channel `next` and fails as this version already exists
#### Merging into a release branch
When merging commits associated with a release from one release branch to another, **semantic-release** will make the corresponding version available on the channel associated with the target branch.
When merging commits not associated with a release, commits from a [maintenance branch](#maintenance-branches) or commits from a [pre-release branch](#pre-release-branches) **semantic-release** will treat them as [pushed commits](#pushing-to-a-release-branch) and publish a new release if necessary.
### Maintenance branches
A maintenance branch is a type of branch used by **semantic-release** that allows to publish releases with a [semantic version](https://semver.org) on top of the codebase of an old release. This is useful when you need to provide fixes or features to users who cannot upgrade to the last version of your package.
A maintenance branch is characterized by a range which defines the versions that can be published from it. The [`range`](#range) value of each maintenance branch must be unique across the project.
**semantic-release** will always publish releases to a distribution channel specific to the range, so only the users who choose to use that particular line of versions will receive new releases.
Maintenance branches are always considered lower than [release branches](#release-branches) and similarly to them, when a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them.
**semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release or maintenance branch to another maintenance branch](#merging-into-a-maintenance-branch), however only version version within the branch `range` can be merged. Ia merged version is outside the maintenance branch `range` **semantic-release** will not add to the corresponding channel and will throw an `EINVALIDMAINTENANCEMERGE` error.
See [publishing maintenance releases recipe](../recipes/maintenance-releases.md) for a detailed example.
#### Pushing to a maintenance branch
With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.5.0` then:
- Only versions in range `>=1.0.0 <1.1.0` can be published from `1.0.x`, so only `fix` commits can be pushed to `1.0.x`
- Only versions in range `>=1.1.0 <1.5.0` can be published from `1.x`, so only `fix` and `feat` commits can be pushed to `1.x` as long the resulting release is lower than `1.5.0`
- Once `2.0.0` is released from `master`, versions in range `>=1.1.0 <2.0.0` can be published from `1.x`, so any number of `fix` and `feat` commits can be pushed to `1.x`
#### Merging into a maintenance branch
With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.0.0` then:
- Creating the branch `1.0.x` from `master` will make the `1.0.0` release available on the `1.0.x` distribution channel
- Pushing a `fix` commit on the `1.0.x` branch will release the version `1.0.1` on the `1.0.x` distribution channel
- Creating the branch `1.x` from `master` will make the `1.0.0` release available on the `1.x` distribution channel
- Merging the branch `1.0.x` into `1.x` will make the version `1.0.1` available on the `1.x` distribution channel
### Pre-release branches
A pre-release branch is a type of branch used by **semantic-release** that allows to publish releases with a [pre-release version](https://semver.org/#spec-item-9).
Using a pre-release version allow to publish multiple releases with the same version. Those release will be differentiated via there identifiers (in `1.0.0-alpha.1` the identifier is `alpha.1`).
This is useful when you need to work on a future major release that will include many breaking changes but you do not want to increment the version number for each breaking change commit.
A pre-release branch is characterized by the `prerelease` property that defines the static part of the version released (in `1.0.0-alpha.1` the static part fo the identifier is `alpha`). The [`prerelease`](#prerelease) value of each pre-release branch must be unique across the project.
**semantic-release** will always publish pre-releases to a specific distribution channel, so only the users who choose to use that particular line of versions will receive new releases.
When merging commits associated with an existing release, **semantic-release** will treat them as [pushed commits](#pushing-to-a-pre-release-branch) and publish a new release if necessary, but it will never add those releases to the distribution channel corresponding to the pre-release branch.
See [publishing pre-releases recipe](../recipes/pre-releases.md) for a detailed example.
#### Pushing to a pre-release branch
With the configuration `"branches": ["master", {"name": "beta", "prerelease": true}]`, if the last release published from `master` is `1.0.0` then:
- Pushing a `BREAKING CHANGE` commit on the `beta` branch will release the version `2.0.0-beta.1` on the `beta` distribution channel
- Pushing either a `fix`, `feat` or a `BREAKING CHANGE` commit on the `beta` branch will release the version `2.0.0-beta.2` (then `2.0.0-beta.3`, `2.0.0-beta.4`, etc...) on the `beta` distribution channel
#### Merging into a pre-release branch
With the configuration `"branches": ["master", {"name": "beta", "prerelease": true}]`, if the last release published from `master` is `1.0.0` and the last one published from `beta` is `2.0.0-beta.1` then:
- Pushing a `fix` commit on the `master` branch will release the version `1.0.1` on the default distribution channel
- Merging the branch `master` into `beta` will release the version `2.0.0-beta.2` on the `beta` distribution channel