style: prettier (#2624)
This commit is contained in:
Gregor Martynus
@@ -3,43 +3,48 @@
|
||||
## Usage
|
||||
|
||||
```js
|
||||
const semanticRelease = require('semantic-release');
|
||||
const {WritableStreamBuffer} = require('stream-buffers');
|
||||
const semanticRelease = require("semantic-release");
|
||||
const { WritableStreamBuffer } = require("stream-buffers");
|
||||
|
||||
const stdoutBuffer = WritableStreamBuffer();
|
||||
const stderrBuffer = WritableStreamBuffer();
|
||||
|
||||
try {
|
||||
const result = await semanticRelease({
|
||||
// Core options
|
||||
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',
|
||||
// Plugin options
|
||||
githubUrl: 'https://my-ghe.com',
|
||||
githubApiPathPrefix: '/api-prefix'
|
||||
}, {
|
||||
// Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
|
||||
cwd: '/path/to/git/repo/root',
|
||||
// Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
|
||||
env: {...process.env, MY_ENV_VAR: 'MY_ENV_VAR_VALUE'},
|
||||
// Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
|
||||
stdout: stdoutBuffer,
|
||||
stderr: stderrBuffer
|
||||
});
|
||||
const result = await semanticRelease(
|
||||
{
|
||||
// Core options
|
||||
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",
|
||||
// Plugin options
|
||||
githubUrl: "https://my-ghe.com",
|
||||
githubApiPathPrefix: "/api-prefix",
|
||||
},
|
||||
{
|
||||
// Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
|
||||
cwd: "/path/to/git/repo/root",
|
||||
// Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
|
||||
env: { ...process.env, MY_ENV_VAR: "MY_ENV_VAR_VALUE" },
|
||||
// Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
|
||||
stdout: stdoutBuffer,
|
||||
stderr: stderrBuffer,
|
||||
}
|
||||
);
|
||||
|
||||
if (result) {
|
||||
const {lastRelease, commits, nextRelease, releases} = result;
|
||||
const { lastRelease, commits, nextRelease, releases } = result;
|
||||
|
||||
console.log(`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`);
|
||||
console.log(
|
||||
`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`
|
||||
);
|
||||
|
||||
if (lastRelease.version) {
|
||||
console.log(`The last release was "${lastRelease.version}".`);
|
||||
@@ -49,14 +54,14 @@ try {
|
||||
console.log(`The release was published with plugin "${release.pluginName}".`);
|
||||
}
|
||||
} else {
|
||||
console.log('No release published.');
|
||||
console.log("No release published.");
|
||||
}
|
||||
|
||||
// Get stdout and stderr content
|
||||
const logs = stdoutBuffer.getContentsAsString('utf8');
|
||||
const errors = stderrBuffer.getContentsAsString('utf8');
|
||||
const logs = stdoutBuffer.getContentsAsString("utf8");
|
||||
const errors = stderrBuffer.getContentsAsString("utf8");
|
||||
} catch (err) {
|
||||
console.error('The automated release failed with %O', err)
|
||||
console.error("The automated release failed with %O", err);
|
||||
}
|
||||
```
|
||||
|
||||
@@ -131,7 +136,7 @@ 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. |
|
||||
@@ -140,6 +145,7 @@ Information related to the last release found:
|
||||
**Notes**: If no previous release is found, `lastRelease` will be an empty `Object`.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
{
|
||||
gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
|
||||
@@ -157,7 +163,7 @@ The list of commit included in the new release.<br>
|
||||
Each commit object has the following properties:
|
||||
|
||||
| Name | Type | Description |
|
||||
|-----------------|----------|-------------------------------------------------|
|
||||
| --------------- | -------- | ----------------------------------------------- |
|
||||
| commit | `Object` | The commit abbreviated and full hash. |
|
||||
| commit.long | `String` | The commit hash. |
|
||||
| commit.short | `String` | The commit abbreviated hash. |
|
||||
@@ -179,6 +185,7 @@ Each commit object has the following properties:
|
||||
| committerDate | `String` | The committer date. |
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
[
|
||||
{
|
||||
@@ -216,7 +223,7 @@ 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. |
|
||||
@@ -225,6 +232,7 @@ Information related to the newly published release:
|
||||
| channel | `String` | The distribution channel on which the next release will be made available (`undefined` for the default distribution channel). |
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
{
|
||||
type: 'minor',
|
||||
@@ -244,7 +252,7 @@ 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`). |
|
||||
@@ -256,6 +264,7 @@ Each release object has the following properties:
|
||||
| channel | `String` | The distribution channel on which the release is available (`undefined` for the default distribution channel). |
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
[
|
||||
{
|
||||
|
||||
@@ -34,7 +34,7 @@ We recommend you setup a linting system to ensure good javascript practices are
|
||||
In your `index.js` file, you can start by writing the following code
|
||||
|
||||
```javascript
|
||||
const verify = require('./src/verify');
|
||||
const verify = require("./src/verify");
|
||||
|
||||
let verified;
|
||||
|
||||
@@ -54,7 +54,7 @@ module.exports = { verifyConditions };
|
||||
Then, in your `src` folder, create a file called `verify.js` and add the following
|
||||
|
||||
```javascript
|
||||
const AggregateError = require('aggregate-error');
|
||||
const AggregateError = require("aggregate-error");
|
||||
|
||||
/**
|
||||
* A method to verify that the user has given us a slack webhook url to post to
|
||||
@@ -80,10 +80,10 @@ Let's say we want to verify that an `option` is passed. An `option` is a configu
|
||||
|
||||
```js
|
||||
{
|
||||
prepare: {
|
||||
path: "@semantic-release/my-special-plugin"
|
||||
message: "My cool release message"
|
||||
}
|
||||
prepare: {
|
||||
path: "@semantic-release/my-special-plugin";
|
||||
message: "My cool release message";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -93,7 +93,7 @@ This `message` option will be passed to the `pluginConfig` object mentioned earl
|
||||
const { message } = pluginConfig;
|
||||
|
||||
if (message.length) {
|
||||
//...
|
||||
//...
|
||||
}
|
||||
```
|
||||
|
||||
@@ -101,103 +101,104 @@ if (message.length) {
|
||||
|
||||
### Common context keys
|
||||
|
||||
* `stdout`
|
||||
* `stderr`
|
||||
* `logger`
|
||||
- `stdout`
|
||||
- `stderr`
|
||||
- `logger`
|
||||
|
||||
### Context object keys by lifecycle
|
||||
|
||||
#### verifyConditions
|
||||
|
||||
Initially the context object contains the following keys (`verifyConditions` lifecycle):
|
||||
* `cwd`
|
||||
* Current working directory
|
||||
* `env`
|
||||
* Environment variables
|
||||
* `envCi`
|
||||
* Information about CI environment
|
||||
* Contains (at least) the following keys:
|
||||
* `isCi`
|
||||
* Boolean, true if the environment is a CI environment
|
||||
* `commit`
|
||||
* Commit hash
|
||||
* `branch`
|
||||
* Current branch
|
||||
* `options`
|
||||
* Options passed to `semantic-release` via CLI, configuration files etc.
|
||||
* `branch`
|
||||
* Information on the current branch
|
||||
* Object keys:
|
||||
* `channel`
|
||||
* `tags`
|
||||
* `type`
|
||||
* `name`
|
||||
* `range`
|
||||
* `accept`
|
||||
* `main`
|
||||
* `branches`
|
||||
* Information on branches
|
||||
* List of branch objects (see above)
|
||||
|
||||
- `cwd`
|
||||
- Current working directory
|
||||
- `env`
|
||||
- Environment variables
|
||||
- `envCi`
|
||||
- Information about CI environment
|
||||
- Contains (at least) the following keys:
|
||||
- `isCi`
|
||||
- Boolean, true if the environment is a CI environment
|
||||
- `commit`
|
||||
- Commit hash
|
||||
- `branch`
|
||||
- Current branch
|
||||
- `options`
|
||||
- Options passed to `semantic-release` via CLI, configuration files etc.
|
||||
- `branch`
|
||||
- Information on the current branch
|
||||
- Object keys:
|
||||
- `channel`
|
||||
- `tags`
|
||||
- `type`
|
||||
- `name`
|
||||
- `range`
|
||||
- `accept`
|
||||
- `main`
|
||||
- `branches`
|
||||
- Information on branches
|
||||
- List of branch objects (see above)
|
||||
|
||||
#### analyzeCommits
|
||||
|
||||
Compared to the verifyConditions, `analyzeCommits` lifecycle context has keys
|
||||
|
||||
* `commits` (List)
|
||||
* List of commits taken into account when determining the new version.
|
||||
* Keys:
|
||||
* `commit` (Object)
|
||||
* Keys:
|
||||
* `long` (String, Commit hash)
|
||||
* `short` (String, Commit hash)
|
||||
* `tree` (Object)
|
||||
* Keys:
|
||||
* `long` (String, Commit hash)
|
||||
* `short` (String, Commit hash)
|
||||
* `author` (Object)
|
||||
* Keys:
|
||||
* `name` (String)
|
||||
* `email` (String)
|
||||
* `date` (String, ISO 8601 timestamp)
|
||||
* `committer` (Object)
|
||||
* Keys:
|
||||
* `name` (String)
|
||||
* `email` (String)
|
||||
* `date` (String, ISO 8601 timestamp)
|
||||
* `subject` (String, Commit message subject)
|
||||
* `body` (String, Commit message body)
|
||||
* `hash` (String, Commit hash)
|
||||
* `committerDate` (String, ISO 8601 timestamp)
|
||||
* `message` (String)
|
||||
* `gitTags` (String, List of git tags)
|
||||
* `releases` (List)
|
||||
* `lastRelease` (Object)
|
||||
* Keys
|
||||
* `version` (String)
|
||||
* `gitTag` (String)
|
||||
* `channels` (List)
|
||||
* `gitHead` (String, Commit hash)
|
||||
* `name` (String)
|
||||
- `commits` (List)
|
||||
- List of commits taken into account when determining the new version.
|
||||
- Keys:
|
||||
- `commit` (Object)
|
||||
- Keys:
|
||||
- `long` (String, Commit hash)
|
||||
- `short` (String, Commit hash)
|
||||
- `tree` (Object)
|
||||
- Keys:
|
||||
- `long` (String, Commit hash)
|
||||
- `short` (String, Commit hash)
|
||||
- `author` (Object)
|
||||
- Keys:
|
||||
- `name` (String)
|
||||
- `email` (String)
|
||||
- `date` (String, ISO 8601 timestamp)
|
||||
- `committer` (Object)
|
||||
- Keys:
|
||||
- `name` (String)
|
||||
- `email` (String)
|
||||
- `date` (String, ISO 8601 timestamp)
|
||||
- `subject` (String, Commit message subject)
|
||||
- `body` (String, Commit message body)
|
||||
- `hash` (String, Commit hash)
|
||||
- `committerDate` (String, ISO 8601 timestamp)
|
||||
- `message` (String)
|
||||
- `gitTags` (String, List of git tags)
|
||||
- `releases` (List)
|
||||
- `lastRelease` (Object)
|
||||
- Keys
|
||||
- `version` (String)
|
||||
- `gitTag` (String)
|
||||
- `channels` (List)
|
||||
- `gitHead` (String, Commit hash)
|
||||
- `name` (String)
|
||||
|
||||
#### verifyRelease
|
||||
|
||||
Additional keys:
|
||||
|
||||
* `nextRelease` (Object)
|
||||
* `type` (String)
|
||||
* `channel` (String)
|
||||
* `gitHead` (String, Git hash)
|
||||
* `version` (String, version without `v`)
|
||||
* `gitTag` (String, version with `v`)
|
||||
* `name` (String)
|
||||
|
||||
- `nextRelease` (Object)
|
||||
- `type` (String)
|
||||
- `channel` (String)
|
||||
- `gitHead` (String, Git hash)
|
||||
- `version` (String, version without `v`)
|
||||
- `gitTag` (String, version with `v`)
|
||||
- `name` (String)
|
||||
|
||||
#### generateNotes
|
||||
|
||||
No new content in the context.
|
||||
|
||||
#### addChannel
|
||||
|
||||
*This is run only if there are releases that have been merged from a higher branch but not added on the channel of the current branch.*
|
||||
_This is run only if there are releases that have been merged from a higher branch but not added on the channel of the current branch._
|
||||
|
||||
Context content is similar to lifecycle `verifyRelease`.
|
||||
|
||||
@@ -215,8 +216,8 @@ Lifecycles `success` and `fail` are mutually exclusive, only one of them will be
|
||||
|
||||
Additional keys:
|
||||
|
||||
* `releases`
|
||||
* Populated by `publish` lifecycle
|
||||
- `releases`
|
||||
- Populated by `publish` lifecycle
|
||||
|
||||
#### fail
|
||||
|
||||
@@ -224,7 +225,7 @@ Lifecycles `success` and `fail` are mutually exclusive, only one of them will be
|
||||
|
||||
Additional keys:
|
||||
|
||||
* `errors`
|
||||
- `errors`
|
||||
|
||||
### Supporting Environment Variables
|
||||
|
||||
@@ -237,13 +238,15 @@ if (env.GITHUB_TOKEN) {
|
||||
//...
|
||||
}
|
||||
```
|
||||
|
||||
## Logger
|
||||
|
||||
Use `context.logger` to provide debug logging in the plugin.
|
||||
|
||||
```js
|
||||
const { logger } = context;
|
||||
|
||||
logger.log('Some message from plugin.').
|
||||
logger.log('Some message from plugin.').
|
||||
```
|
||||
|
||||
The above usage yields the following where `PLUGIN_PACKAGE_NAME` is automatically inferred.
|
||||
@@ -269,12 +272,13 @@ Knowledge that might be useful for plugin developers.
|
||||
While it may be trivial that multiple analyzeCommits (or any lifecycle plugins) can be defined, it is not that self-evident that the plugins executed AFTER the first one (for example, the default one: `commit-analyzer`) can change the result. This way it is possible to create more advanced rules or situations, e.g. if none of the commits would result in new release, then a default can be defined.
|
||||
|
||||
The commit must be a known release type, for example the commit-analyzer has the following default types:
|
||||
* major
|
||||
* premajor
|
||||
* minor
|
||||
* preminor
|
||||
* patch
|
||||
* prepatch
|
||||
* prerelease
|
||||
|
||||
- major
|
||||
- premajor
|
||||
- minor
|
||||
- preminor
|
||||
- patch
|
||||
- prepatch
|
||||
- prerelease
|
||||
|
||||
If the analyzeCommits-lifecycle plugin does not return anything, then the earlier result is used, but if it returns a supported string value, then that overrides the previous result.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Plugins list
|
||||
|
||||
## Official plugins
|
||||
|
||||
- [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer)
|
||||
- **Note**: this is already part of semantic-release and does not have to be installed separately
|
||||
- `analyzeCommits`: Determine the type of release by analyzing commits with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
|
||||
@@ -111,10 +112,10 @@
|
||||
- [semantic-release-rubygem](https://github.com/Gusto/semantic-release-rubygem)
|
||||
- `verifyConditions`: Locate and validate a `.gemspec` file, locate and validate a `lib/**/version.rb` file, verify the presence of the `GEM_HOST_API_KEY` environment variable, and create a credentials file with the API key.
|
||||
- `prepare`: Update the version in the `lib/**/version.rb` version file and [build](https://guides.rubygems.org/command-reference/#gem-build) the gem.
|
||||
- `publish`: [Push the Ruby gem](https://guides.rubygems.org/command-reference/#gem-push) to the gem server.
|
||||
- `publish`: [Push the Ruby gem](https://guides.rubygems.org/command-reference/#gem-push) to the gem server.
|
||||
- [semantic-release-npm-deprecate-old-versions](https://github.com/ghusse/semantic-release-npm-deprecate-old-versions)
|
||||
- `verifyConditions`: Validates configuration.
|
||||
- `publish`: Deprecates old versions, based on the declaration of supported versions in the config.
|
||||
- `publish`: Deprecates old versions, based on the declaration of supported versions in the config.
|
||||
- [amanda-mitchell/semantic-release-npm-multiple](https://github.com/amanda-mitchell/semantic-release-npm-multiple)
|
||||
- **Note**: this is a thin wrapper around the built-in npm plugin that can target multiple registries
|
||||
- `verifyConditions`: Verify the presence and the validity of the npm authentication and release configuration for multiple registries
|
||||
@@ -124,21 +125,21 @@
|
||||
- `verifyConditions`: Verify the presence of a license file
|
||||
- `prepare`: Update the license file based on its type
|
||||
- [semantic-release-pypi](https://github.com/abichinger/semantic-release-pypi)
|
||||
- `verifyConditions`: Verify the environment variable ```PYPI_TOKEN``` and installation of build tools
|
||||
- `prepare`: Update the version in ```setup.cfg``` and create the distribution packages
|
||||
- `verifyConditions`: Verify the environment variable `PYPI_TOKEN` and installation of build tools
|
||||
- `prepare`: Update the version in `setup.cfg` and create the distribution packages
|
||||
- `publish`: Publish the python package to a repository (default: pypi)
|
||||
- [semantic-release-helm](https://github.com/m1pl/semantic-release-helm)
|
||||
- `verifyConditions`: Validate configuration and (if present) credentials
|
||||
- `prepare`: Update version and appVersion in ```Chart.yaml```
|
||||
- `prepare`: Update version and appVersion in `Chart.yaml`
|
||||
- `publish`: Publish the chart to a registry (if configured)
|
||||
- [semantic-release-codeartifact](https://github.com/ryansonshine/semantic-release-codeartifact)
|
||||
- `verifyConditions`: Validate configuration, get AWS CodeArtifact authentication and repository, validate `publishConfig` or `.npmrc` (if they exist), then pass the configuration to the associated plugins.
|
||||
- [semantic-release-telegram](https://github.com/pustovitDmytro/semantic-release-telegram)
|
||||
- `verifyConditions`: Validate configuration and verify ```TELEGRAM_BOT_ID``` and ```TELEGRAM_BOT_TOKEN```
|
||||
- `verifyConditions`: Validate configuration and verify `TELEGRAM_BOT_ID` and `TELEGRAM_BOT_TOKEN`
|
||||
- `success`: Publish a message about the successful release to a telegram chat
|
||||
- `fail`: publish a message about failure to a telegram chat
|
||||
- [semantic-release-heroku](https://github.com/pustovitDmytro/semantic-release-heroku)
|
||||
- `verifyConditions`: Validate configuration and verify ```HEROKU_API_KEY```
|
||||
- `verifyConditions`: Validate configuration and verify `HEROKU_API_KEY`
|
||||
- `prepare`: Update the package.json version and create release tarball
|
||||
- `publish`: Publish version to heroku
|
||||
- [semantic-release-mattermost](https://github.com/ttrobisch/semantic-release-mattermost)
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
# Shareable configurations list
|
||||
|
||||
## Official configurations
|
||||
|
||||
- [@semantic-release/apm-config](https://github.com/semantic-release/apm-config) - semantic-release shareable configuration for releasing atom packages
|
||||
- [@semantic-release/gitlab-config](https://github.com/semantic-release/gitlab-config) - semantic-release shareable configuration for GitLab
|
||||
|
||||
## Community configurations
|
||||
|
||||
- [@jedmao/semantic-release-npm-github-config](https://github.com/jedmao/semantic-release-npm-github-config)
|
||||
- Provides an informative [Git](https://github.com/semantic-release/git) commit message for the release commit that does not trigger continuous integration and conforms to the [conventional commits specification](https://www.conventionalcommits.org/) (e.g., `chore(release): 1.2.3 [skip ci]\n\nnotes`).
|
||||
- Creates a tarball that gets uploaded with each [GitHub release](https://github.com/semantic-release/github).
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
# CI configurations
|
||||
|
||||
- [CircleCI 2.0 workflows](circleci-workflows.md)
|
||||
- [Travis CI](travis.md)
|
||||
- [GitLab CI](gitlab-ci.md)
|
||||
|
||||
@@ -35,7 +35,7 @@ jobs:
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v2
|
||||
with:
|
||||
node-version: 'lts/*'
|
||||
node-version: "lts/*"
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
- name: Release
|
||||
@@ -64,9 +64,11 @@ If the risk is acceptable, some extra configuration is needed. The [actions/chec
|
||||
## Trigger semantic-release on demand
|
||||
|
||||
### Using GUI:
|
||||
|
||||
You can use [Manual Triggers](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/) for GitHub Actions.
|
||||
|
||||
### Using HTTP:
|
||||
|
||||
Use [`repository_dispatch`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#repository_dispatch) event to have control on when to generate a release by making an HTTP request, e.g.:
|
||||
|
||||
```yaml
|
||||
@@ -85,7 +87,8 @@ $ curl -v -H "Accept: application/vnd.github.everest-preview+json" -H "Authoriza
|
||||
```
|
||||
|
||||
### Using 3rd party apps:
|
||||
|
||||
If you'd like to use a GitHub app to manage this instead of creating a personal access token, you could consider using a project like:
|
||||
|
||||
* [Actions Panel](https://www.actionspanel.app/) - A declaratively configured way for triggering GitHub Actions
|
||||
* [Action Button](https://github-action-button.web.app/#details) - A simple badge based mechanism for triggering GitHub Actions
|
||||
- [Actions Panel](https://www.actionspanel.app/) - A declaratively configured way for triggering GitHub Actions
|
||||
- [Action Button](https://github-action-button.web.app/#details) - A simple badge based mechanism for triggering GitHub Actions
|
||||
|
||||
@@ -21,8 +21,8 @@ This example is a minimal configuration for **semantic-release** with a build ru
|
||||
```yaml
|
||||
# The release pipeline will run only if all jobs in the test pipeline are successful
|
||||
stages:
|
||||
- test
|
||||
- release
|
||||
- test
|
||||
- release
|
||||
|
||||
before_script:
|
||||
- npm install
|
||||
@@ -52,7 +52,6 @@ This example is a minimal configuration for **semantic-release** with a build ru
|
||||
|
||||
**Note**: The`semantic-release` execution command varies depending if you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation.
|
||||
|
||||
|
||||
```yaml
|
||||
# The release pipeline will run only on the master branch a commit is triggered
|
||||
stages:
|
||||
|
||||
@@ -1,2 +1,3 @@
|
||||
# Git hosted services
|
||||
|
||||
- [Git authentication with SSH keys](git-auth-ssh-keys.md)
|
||||
|
||||
@@ -21,6 +21,7 @@ This will generate a public key in `git_deploy_key.pub` and a private key in `gi
|
||||
## Adding the SSH public key to the Git hosted account
|
||||
|
||||
Step by step instructions are provided for the following Git hosted services:
|
||||
|
||||
- [GitHub](#adding-the-ssh-public-key-to-github)
|
||||
|
||||
### Adding the SSH public key to GitHub
|
||||
@@ -44,6 +45,7 @@ See [Adding a new SSH key to your GitHub account](https://help.github.com/articl
|
||||
In order to be available on the CI environment, the SSH private key must be encrypted, committed to the Git repository and decrypted by the CI service.
|
||||
|
||||
Step by step instructions are provided for the following environments:
|
||||
|
||||
- [Travis CI](#adding-the-ssh-private-key-to-travis-ci)
|
||||
- [Circle CI](#adding-the-ssh-private-key-to-circle-ci)
|
||||
|
||||
@@ -109,7 +111,7 @@ $ git push
|
||||
|
||||
### Adding the SSH private key to Circle CI
|
||||
|
||||
First we encrypt the `git_deploy_key` (private key) using a symmetric encryption (AES-256). Run the following `openssl` command and *make sure to note the output which we'll need later*:
|
||||
First we encrypt the `git_deploy_key` (private key) using a symmetric encryption (AES-256). Run the following `openssl` command and _make sure to note the output which we'll need later_:
|
||||
|
||||
```bash
|
||||
$ openssl aes-256-cbc -e -p -in git_deploy_key -out git_deploy_key.enc -K `openssl rand -hex 32` -iv `openssl rand -hex 16`
|
||||
@@ -119,6 +121,7 @@ iv =VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV
|
||||
```
|
||||
|
||||
Add the following [environment variables](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app) to Circle CI:
|
||||
|
||||
- `SSL_PASSPHRASE` - the value set during the [SSH keys generation](#generating-the-ssh-keys) step.
|
||||
- `REPO_ENC_KEY` - the `key` (KKK) value from the `openssl` step above.
|
||||
- `REPO_ENC_IV` - the `iv` (VVV) value from the `openssl` step above.
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
# Release workflow
|
||||
|
||||
- [Publishing on distribution channels](distribution-channels.md)
|
||||
- [Publishing maintenance releases](maintenance-releases.md)
|
||||
- [Publishing pre-releases](pre-releases.md)
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
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 feedback before distributing the release to all users.
|
||||
|
||||
This example uses the **semantic-release** default configuration:
|
||||
|
||||
- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-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']`
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
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): `['+([0-9])?(.{+([0-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']`
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
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): `['+([0-9])?(.{+([0-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']`
|
||||
|
||||
|
||||
+25
-14
@@ -4,7 +4,7 @@
|
||||
|
||||
[`@semantic-release/npm`](https://github.com/semantic-release/npm) takes care of updating the `package.json`’s version before publishing to [npm](https://www.npmjs.com).
|
||||
|
||||
By default, only the published package will contain the version, which is the only place where it is *really* required, but the updated `package.json` will not be pushed to the Git repository
|
||||
By default, only the published package will contain the version, which is the only place where it is _really_ required, but the updated `package.json` will not be pushed to the Git repository
|
||||
|
||||
However, the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used to push the updated `package.json` as well as other files to the Git repository.
|
||||
|
||||
@@ -17,19 +17,24 @@ The `package.json`’s version will be updated by the `semantic-release` command
|
||||
As the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin uses the [npm CLI](https://docs.npmjs.com/cli/npm) to update the `package.json` version and publish the package, all [npm hook scripts](https://docs.npmjs.com/misc/scripts#description) will be executed.
|
||||
|
||||
You can run your build script in:
|
||||
|
||||
- the `prepublishOnly` or `prepack` hook so it will be executed during the `publish` step of `@semantic-release/npm`
|
||||
- the `postversion` hook so it will be executed during the `prepare` step of `@semantic-release/npm`, which allow for example to update files before committing them with the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin
|
||||
|
||||
If using npm hook scripts is not possible, and alternative solution is to [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin to run your script in the `prepare` step:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
"@semantic-release/commit-analyzer",
|
||||
"@semantic-release/release-notes-generator",
|
||||
"@semantic-release/npm",
|
||||
["@semantic-release/exec", {
|
||||
"prepareCmd": "./my-build-script.sh ${nextRelease.version}",
|
||||
}],
|
||||
[
|
||||
"@semantic-release/exec",
|
||||
{
|
||||
"prepareCmd": "./my-build-script.sh ${nextRelease.version}"
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -43,6 +48,7 @@ Yes with the [dry-run options](../usage/configuration.md#dryrun) which prints to
|
||||
Yes, **semantic-release** is a Node CLI application, but it can be used to publish any type of packages.
|
||||
|
||||
To publish a non-Node package (without a `package.json`) you would need to:
|
||||
|
||||
- Use a [global](../usage/installation.md#global-installation) **semantic-release** installation
|
||||
- Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or `.rc` file](../usage/configuration.md#configuration)
|
||||
- Make sure your CI job executing the `semantic-release` command has access to a version of Node that [meets our version requirement](./node-version.md) to execute the `semantic-release` command
|
||||
@@ -61,10 +67,13 @@ Here is a basic example to create [GitHub releases](https://help.github.com/arti
|
||||
"@semantic-release/commit-analyzer",
|
||||
"@semantic-release/release-notes-generator",
|
||||
"@semantic-release/github",
|
||||
["@semantic-release/exec", {
|
||||
"prepareCmd" : "set-version ${nextRelease.version}",
|
||||
"publishCmd" : "publish-package"
|
||||
}]
|
||||
[
|
||||
"@semantic-release/exec",
|
||||
{
|
||||
"prepareCmd": "set-version ${nextRelease.version}",
|
||||
"publishCmd": "publish-package"
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -76,6 +85,7 @@ See the [package managers and languages recipes](../recipes/release-workflow/REA
|
||||
## Can I use semantic-release with any CI service?
|
||||
|
||||
Yes, **semantic-release** can be used with any CI service, as long as it provides:
|
||||
|
||||
- A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables
|
||||
- A way to guarantee that the `semantic-release` command is [executed only after all the tests of all the jobs in the CI build pass](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
|
||||
|
||||
@@ -99,7 +109,7 @@ See the [GitLab CI recipes](../recipes/ci-configurations/gitlab-ci.md#using-sema
|
||||
|
||||
## Can I use semantic-release with any Git hosted environment?
|
||||
|
||||
By default **semantic-release** uses the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin to publish a [GitHub release](https://help.github.com/articles/about-releases). For other Git hosted environment the [`@semantic-release/git`](https://github.com/semantic-release/git) and [`@semantic-release/changelog`](https://github.com/semantic-release/changelog) plugins can be used via [plugins configuration](../usage/plugins.md).
|
||||
By default **semantic-release** uses the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin to publish a [GitHub release](https://help.github.com/articles/about-releases). For other Git hosted environment the [`@semantic-release/git`](https://github.com/semantic-release/git) and [`@semantic-release/changelog`](https://github.com/semantic-release/changelog) plugins can be used via [plugins configuration](../usage/plugins.md).
|
||||
|
||||
See the [`@semantic-release/git`](https://github.com/semantic-release/git#semantic-releasegit) [`@semantic-release/changelog`](https://github.com/semantic-release/changelog#semantic-releasechangelog) plugins documentation for more details.
|
||||
|
||||
@@ -112,6 +122,7 @@ See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#semant
|
||||
## How can I revert a release?
|
||||
|
||||
If you have introduced a breaking bug in a release you have 2 options:
|
||||
|
||||
- If you have a fix immediately ready, commit and push it (or merge it via a pull request) to the release branch
|
||||
- Otherwise, [revert the commit](https://git-scm.com/docs/git-revert) that introduced the bug and push the revert commit (or merge it via a pull request) to the release branch
|
||||
|
||||
@@ -121,7 +132,7 @@ Depending on the package manager you are using, you might be able to un-publish
|
||||
|
||||
In any case **do not remove the Git tag associated with the buggy version**, otherwise **semantic-release** will later try to republish that version. Publishing a version after un-publishing is not supported by most package managers.
|
||||
|
||||
**Note**: If you are using the default [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) be aware that it uses a different revert commit format than the standard one created by [git revert](https://git-scm.com/docs/git-revert), contrary to what is [claimed in the convention](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). Therefore, if you revert a commit with [`git revert`](https://git-scm.com/docs/git-revert), use the [`--edit` option](https://git-scm.com/docs/git-revert#git-revert---edit) to format the message according to the [Angular revert commit message format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). See [conventional-changelog/conventional-changelog#348](https://github.com/conventional-changelog/conventional-changelog/issues/348) for more details.
|
||||
**Note**: If you are using the default [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) be aware that it uses a different revert commit format than the standard one created by [git revert](https://git-scm.com/docs/git-revert), contrary to what is [claimed in the convention](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). Therefore, if you revert a commit with [`git revert`](https://git-scm.com/docs/git-revert), use the [`--edit` option](https://git-scm.com/docs/git-revert#git-revert---edit) to format the message according to the [Angular revert commit message format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). See [conventional-changelog/conventional-changelog#348](https://github.com/conventional-changelog/conventional-changelog/issues/348) for more details.
|
||||
|
||||
## Can I use `.npmrc` options?
|
||||
|
||||
@@ -157,7 +168,7 @@ See [Artifactory - npm Registry](https://www.jfrog.com/confluence/display/RTF/Np
|
||||
|
||||
## Can I manually trigger the release of a specific version?
|
||||
|
||||
You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a *specific* version release, because this is the whole point of semantic-release.
|
||||
You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a _specific_ version release, because this is the whole point of semantic-release.
|
||||
|
||||
## Can I exclude commits from the analysis?
|
||||
|
||||
@@ -168,7 +179,7 @@ Yes, every commits that contains `[skip release]` or `[release skip]` in their m
|
||||
By default **semantic-release** uses the [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) and triggers releases based on the following rules:
|
||||
|
||||
| Commit | Release type |
|
||||
|-----------------------------|----------------------------|
|
||||
| --------------------------- | -------------------------- |
|
||||
| Commit with breaking change | ~~Major~~ Breaking release |
|
||||
| Commit with type `feat` | ~~Minor~~ Feature release |
|
||||
| Commit with type `fix` | Patch release |
|
||||
@@ -178,9 +189,9 @@ See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#npm-co
|
||||
|
||||
This is fully customizable with the [`@semantic-release/commit-analyzer`](https://github.com/semantic-release/commit-analyzer) plugin's [`release-rules` option](https://github.com/semantic-release/commit-analyzer#release-rules).
|
||||
|
||||
## Is it *really* a good idea to release on every push?
|
||||
## 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 releasing every feature or fix on your `master` you might not treat your `master` branch as intended.
|
||||
It is indeed a great idea because it _forces_ you to follow best practices. If you don’t feel comfortable releasing every feature or fix on your `master` you might not treat your `master` branch as intended.
|
||||
|
||||
From [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/index.html):
|
||||
|
||||
|
||||
@@ -15,6 +15,7 @@ This is most likely related to a misconfiguration of the [npm registry authentic
|
||||
It might also happen if the package name you are trying to publish already exists (in the case of npm, you may be trying to publish a new version of a package that is not yours, hence the permission error).
|
||||
|
||||
To verify if your package name is available you can use [npm-name-cli](https://github.com/sindresorhus/npm-name-cli):
|
||||
|
||||
```bash
|
||||
$ npm install --global npm-name-cli
|
||||
$ npm-name <package-name>
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
|
||||
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.
|
||||
Here are a few examples of the CI services that can be used to achieve this:
|
||||
|
||||
- [Travis Build Stages](https://docs.travis-ci.com/user/build-stages)
|
||||
- [CircleCI Workflows](https://circleci.com/docs/2.0/workflows)
|
||||
- [GitHub Actions](https://github.com/features/actions)
|
||||
@@ -22,11 +23,11 @@ See [CI configuration recipes](../recipes/ci-configurations#ci-configurations) f
|
||||
**semantic-release** requires push access to the project Git repository in order to create [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). The Git authentication can be set with one of the following environment variables:
|
||||
|
||||
| Variable | Description |
|
||||
|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `GH_TOKEN` or `GITHUB_TOKEN` | A GitHub [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line). |
|
||||
| `GL_TOKEN` or `GITLAB_TOKEN` | A GitLab [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html). |
|
||||
| `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html). |
|
||||
| `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clarification `user:token` has to be the value of this env. |
|
||||
| `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clarification `user:token` has to be the value of this env. |
|
||||
| `GIT_CREDENTIALS` | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) Git username and password in the format `<username>:<password>`. The username and password must each be individually URL encoded, not the `:` separating them. |
|
||||
|
||||
Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-hosted-services/git-auth-ssh-keys.md).
|
||||
@@ -36,7 +37,7 @@ Alternatively the Git authentication can be set up via [SSH keys](../recipes/git
|
||||
Most **semantic-release** [plugins](plugins.md) require setting up authentication in order to publish to a package manager registry. The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) and [@semantic-release/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. |
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Configuration
|
||||
|
||||
**semantic-release** configuration consists of:
|
||||
|
||||
- Git repository ([URL](#repositoryurl) and options [release branches](#branches) and [tag format](#tagformat))
|
||||
- Plugins [declaration](#plugins) and options
|
||||
- Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
|
||||
@@ -12,6 +13,7 @@ Additionally, metadata of Git tags generated by **semantic-release** can be cust
|
||||
## Configuration file
|
||||
|
||||
**semantic-release**’s [options](#options), mode and [plugins](plugins.md) can be set via either:
|
||||
|
||||
- A `.releaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`/`.cjs`
|
||||
- A `release.config.(js|cjs)` file that exports an object
|
||||
- A `release` key in the project's `package.json` file
|
||||
@@ -21,6 +23,7 @@ Alternatively, some options can be set via CLI arguments.
|
||||
The following three examples are the same.
|
||||
|
||||
- Via `release` key in the project's `package.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"release": {
|
||||
@@ -30,6 +33,7 @@ The following three examples are the same.
|
||||
```
|
||||
|
||||
- Via `.releaserc` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"branches": ["master", "next"]
|
||||
@@ -37,6 +41,7 @@ The following three examples are the same.
|
||||
```
|
||||
|
||||
- Via CLI argument:
|
||||
|
||||
```bash
|
||||
$ semantic-release --branches next
|
||||
```
|
||||
@@ -65,10 +70,11 @@ Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name:
|
||||
CLI arguments: `--branches`
|
||||
|
||||
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
|
||||
- regular releases to the `next-major` distribution channel from the branch `next-major` if it exists
|
||||
- pre-releases to the `beta` distribution channel from the branch `beta` if it exists
|
||||
- pre-releases to the `alpha` distribution channel from the branch `alpha` if it exists
|
||||
|
||||
@@ -143,7 +149,7 @@ Output debugging information. This can also be enabled by setting the `DEBUG` en
|
||||
## Git environment variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
|
||||
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
|
||||
| `GIT_AUTHOR_NAME` | The author name associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing). | @semantic-release-bot. |
|
||||
| `GIT_AUTHOR_EMAIL` | The author email associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing). | @semantic-release-bot email address. |
|
||||
| `GIT_COMMITTER_NAME` | The committer name associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing). | @semantic-release-bot. |
|
||||
|
||||
+10
-4
@@ -5,7 +5,7 @@ Each [release step](../../README.md#release-steps) is implemented by configurabl
|
||||
A plugin is a npm module that can implement one or more of the following steps:
|
||||
|
||||
| Step | Required | Description |
|
||||
|--------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `verifyConditions` | No | Responsible for verifying conditions necessary to proceed with the release: configuration is correct, authentication token are valid, etc... |
|
||||
| `analyzeCommits` | Yes | Responsible for determining the type of the next release (`major`, `minor` or `patch`). If multiple plugins with a `analyzeCommits` step are defined, the release type will be the highest one among plugins output. |
|
||||
| `verifyRelease` | No | Responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published. |
|
||||
@@ -25,6 +25,7 @@ Release steps will run in that order. At each step, **semantic-release** will ru
|
||||
### Default plugins
|
||||
|
||||
These four plugins are already part of **semantic-release** and are listed in order of execution. They do not have to be installed separately:
|
||||
|
||||
```
|
||||
"@semantic-release/commit-analyzer"
|
||||
"@semantic-release/release-notes-generator"
|
||||
@@ -66,6 +67,7 @@ For each [release step](../../README.md#release-steps) the plugins that implemen
|
||||
```
|
||||
|
||||
With this configuration **semantic-release** will:
|
||||
|
||||
- execute the `verifyConditions` implementation of `@semantic-release/npm` then `@semantic-release/git`
|
||||
- execute the `analyzeCommits` implementation of `@semantic-release/commit-analyzer`
|
||||
- execute the `generateNotes` implementation of `@semantic-release/release-notes-generator`
|
||||
@@ -85,9 +87,12 @@ Global plugin configuration can be defined at the root of the **semantic-release
|
||||
"plugins": [
|
||||
"@semantic-release/commit-analyzer",
|
||||
"@semantic-release/release-notes-generator",
|
||||
["@semantic-release/github", {
|
||||
"assets": ["dist/**"]
|
||||
}],
|
||||
[
|
||||
"@semantic-release/github",
|
||||
{
|
||||
"assets": ["dist/**"]
|
||||
}
|
||||
],
|
||||
"@semantic-release/git"
|
||||
],
|
||||
"preset": "angular"
|
||||
@@ -95,5 +100,6 @@ Global plugin configuration can be defined at the root of the **semantic-release
|
||||
```
|
||||
|
||||
With this configuration:
|
||||
|
||||
- All plugins will receive the `preset` option, which will be used by both `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` (and ignored by `@semantic-release/github` and `@semantic-release/git`)
|
||||
- The `@semantic-release/github` plugin will receive the `assets` options (`@semantic-release/git` will not receive it and therefore will use it's default value for that option)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Workflow configuration
|
||||
|
||||
**semantic-release** allow to manage and automate complex release workflow, based on multiple Git branches and distribution channels. This allow to:
|
||||
|
||||
- Distribute 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 parallel
|
||||
@@ -12,6 +13,7 @@ The release workflow is configured via the [branches option](./configuration.md#
|
||||
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 releases on top of an old release
|
||||
- [pre-release](#pre-release-branches): to make pre-releases
|
||||
@@ -21,7 +23,7 @@ The type of the branch is automatically determined based on naming convention an
|
||||
## 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. Set to `false` to force the default distribution channel instead of using the default. 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`. |
|
||||
@@ -35,14 +37,15 @@ It can be defined as a [glob](https://github.com/micromatch/micromatch#matching-
|
||||
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 `['+([0-9])?(.{+([0-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
|
||||
]
|
||||
{ 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
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -54,12 +57,13 @@ If the `channel` property is set to `false` the default channel will be used.
|
||||
The value of `channel`, 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: '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}`
|
||||
]
|
||||
{ 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}`
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -68,13 +72,14 @@ For example the configuration `['master', {name: 'next', channel: 'channel-${nam
|
||||
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'},
|
||||
]
|
||||
{ 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" },
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -86,13 +91,14 @@ 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: true}, // `prerelease` is set to `beta` as it is the value of `name`
|
||||
]
|
||||
{ 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: true }, // `prerelease` is set to `beta` as it is the value of `name`
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -113,10 +119,12 @@ See [publishing on distribution channels recipe](../recipes/release-workflow/dis
|
||||
#### Pushing to a release branch
|
||||
|
||||
With the configuration `"branches": ["master", "next"]`, if the last release published from `master` is `1.0.0` and the last one from `next` is `2.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`
|
||||
- Once `next` get merged into `master` the release `2.0.0` will be made available on the channel associated with `master` and both `master` and `next` will accept any commit type
|
||||
|
||||
This verification prevent scenario such as:
|
||||
|
||||
1. Create a `feat` commit on `next` which triggers the release of version `1.0.0` on the `next` channel
|
||||
2. Merge `next` into `master` which adds `1.0.0` on the default channel
|
||||
3. Create a `feat` commit on `next` which triggers the release of version `1.1.0` on the `next` channel
|
||||
@@ -147,6 +155,7 @@ See [publishing maintenance releases recipe](../recipes/release-workflow/mainten
|
||||
#### 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`
|
||||
@@ -154,6 +163,7 @@ With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last rel
|
||||
#### 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
|
||||
@@ -176,11 +186,13 @@ See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md
|
||||
#### 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
|
||||
|
||||
Reference in New Issue
Block a user