docs(recipes): moved recipes to sub-directories to align with gitbook expectations (#2246)
This commit is contained in:
Matt Travi
GitHub
parent
52d76a2a97
commit
8fda7fd423
@ -20,7 +20,7 @@ Help us keep **semantic-release** open and inclusive. Please read and follow our
|
||||
|
||||
### Improve documentation
|
||||
|
||||
As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes/README.md), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+).
|
||||
As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+).
|
||||
|
||||
Please follow the [Documentation guidelines](#documentation).
|
||||
|
||||
|
||||
18
README.md
18
README.md
@ -37,9 +37,9 @@ This removes the immediate connection between human emotions and version numbers
|
||||
- Notify maintainers and users of new releases
|
||||
- Use formalized commit message convention to document changes in the codebase
|
||||
- Publish on different distribution channels (such as [npm dist-tags](https://docs.npmjs.com/cli/dist-tag)) based on git merges
|
||||
- Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
|
||||
- Integrate with your [continuous integration workflow](docs/recipes/release-workflow/README.md#ci-configurations)
|
||||
- Avoid potential errors associated with manual releases
|
||||
- Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
|
||||
- Support any [package managers and languages](docs/recipes/release-workflow/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
|
||||
- Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
|
||||
|
||||
## How does it work?
|
||||
@ -74,9 +74,9 @@ For each new commit added to one of the release branches (for example: `master`,
|
||||
**semantic-release** offers various ways to control the timing, the content and the audience of published releases.
|
||||
See example workflows in the following recipes:
|
||||
|
||||
- [Using distribution channels](docs/recipes/distribution-channels.md#publishing-on-distribution-channels)
|
||||
- [Maintenance releases](docs/recipes/maintenance-releases.md#publishing-maintenance-releases)
|
||||
- [Pre-releases](docs/recipes/pre-releases.md#publishing-pre-releases)
|
||||
- [Using distribution channels](docs/recipes/release-workflow/distribution-channels.md#publishing-on-distribution-channels)
|
||||
- [Maintenance releases](docs/recipes/release-workflow/maintenance-releases.md#publishing-maintenance-releases)
|
||||
- [Pre-releases](docs/recipes/release-workflow/pre-releases.md#publishing-pre-releases)
|
||||
|
||||
### Release steps
|
||||
|
||||
@ -117,10 +117,10 @@ In order to use **semantic-release** you need:
|
||||
- [Plugins](docs/extending/plugins-list.md)
|
||||
- [Shareable configuration](docs/extending/shareable-configurations-list.md)
|
||||
- Recipes
|
||||
- [CI configurations](docs/recipes/README.md)
|
||||
- [Git hosted services](docs/recipes/README.md)
|
||||
- [Release workflow](docs/recipes/README.md)
|
||||
- [Package managers and languages](docs/recipes/README.md)
|
||||
- [CI configurations](docs/recipes/release-workflow/README.md)
|
||||
- [Git hosted services](docs/recipes/release-workflow/README.md)
|
||||
- [Release workflow](docs/recipes/release-workflow/README.md)
|
||||
- [Package managers and languages](docs/recipes/release-workflow/README.md)
|
||||
- Developer guide
|
||||
- [JavaScript API](docs/developer-guide/js-api.md)
|
||||
- [Plugins development](docs/developer-guide/plugin.md)
|
||||
|
||||
24
SUMMARY.md
24
SUMMARY.md
@ -14,18 +14,18 @@
|
||||
- [Shareable configuration](docs/extending/shareable-configurations-list.md)
|
||||
|
||||
## Recipes
|
||||
- [CI configurations](docs/recipes/README.md#ci-configurations)
|
||||
- [CircleCI 2.0](docs/recipes/circleci-workflows.md)
|
||||
- [Travis CI](docs/recipes/travis.md)
|
||||
- [GitLab CI](docs/recipes/gitlab-ci.md)
|
||||
- [GitHub Actions](docs/recipes/github-actions.md)
|
||||
- [Jenkins CI](docs/recipes/jenkins-ci.md)
|
||||
- [Git hosted services](docs/recipes/README.md#git-hosted-services)
|
||||
- [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md)
|
||||
- [Release Workflow](docs/recipes/README.md#release-workflow)
|
||||
- [Publishing on distribution channels](docs/recipes/distribution-channels.md)
|
||||
- [Publishing maintenance releases](docs/recipes/maintenance-releases.md)
|
||||
- [Publishing pre-releases](docs/recipes/pre-releases.md)
|
||||
- [CI configurations](docs/recipes/ci-configurations/README.md)
|
||||
- [CircleCI 2.0](docs/recipes/ci-configurations/circleci-workflows.md)
|
||||
- [Travis CI](docs/recipes/ci-configurations/travis.md)
|
||||
- [GitLab CI](docs/recipes/ci-configurations/gitlab-ci.md)
|
||||
- [GitHub Actions](docs/recipes/ci-configurations/github-actions.md)
|
||||
- [Jenkins CI](docs/recipes/ci-configurations/jenkins-ci.md)
|
||||
- [Git hosted services](docs/recipes/git-hosted-services/README.md)
|
||||
- [Git authentication with SSH keys](docs/recipes/git-hosted-services/git-auth-ssh-keys.md)
|
||||
- [Release Workflow](docs/recipes/release-workflow/README.md)
|
||||
- [Publishing on distribution channels](docs/recipes/release-workflow/distribution-channels.md)
|
||||
- [Publishing maintenance releases](docs/recipes/release-workflow/maintenance-releases.md)
|
||||
- [Publishing pre-releases](docs/recipes/release-workflow/pre-releases.md)
|
||||
|
||||
## Developer guide
|
||||
- [JavaScript API](docs/developer-guide/js-api.md)
|
||||
|
||||
@ -2,6 +2,6 @@
|
||||
|
||||
- [Usage](usage/README.md) - **semantic-release** installation and configuration
|
||||
- [Extending](extending/README.md) - Extending **semantic-release** with plugins and shareable configurations
|
||||
- [Recipes](recipes/README.md) - Community written recipes for common **semantic-release** use-cases
|
||||
- [Recipes](recipes/release-workflow/README.md) - Community written recipes for common **semantic-release** use-cases
|
||||
- [Developer Guide](developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations
|
||||
- [Support](support/README.md) - FAQ and troubleshooting
|
||||
|
||||
@ -1,16 +0,0 @@
|
||||
# Recipes
|
||||
|
||||
## CI configurations
|
||||
- [CircleCI 2.0 workflows](circleci-workflows.md)
|
||||
- [Travis CI](travis.md)
|
||||
- [GitLab CI](gitlab-ci.md)
|
||||
- [GitHub Actions](github-actions.md)
|
||||
- [Jenkins CI](jenkins-ci.md)
|
||||
|
||||
## 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)
|
||||
6
docs/recipes/ci-configurations/README.md
Normal file
6
docs/recipes/ci-configurations/README.md
Normal file
@ -0,0 +1,6 @@
|
||||
# CI configurations
|
||||
- [CircleCI 2.0 workflows](circleci-workflows.md)
|
||||
- [Travis CI](travis.md)
|
||||
- [GitLab CI](gitlab-ci.md)
|
||||
- [GitHub Actions](github-actions.md)
|
||||
- [Jenkins CI](jenkins-ci.md)
|
||||
@ -2,9 +2,9 @@
|
||||
|
||||
## Environment variables
|
||||
|
||||
The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app)..
|
||||
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app)..
|
||||
|
||||
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
|
||||
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
|
||||
|
||||
## Multiple Node jobs configuration
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## Environment variables
|
||||
|
||||
The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
|
||||
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
|
||||
|
||||
In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) is required to publish a package to the npm registry. GitHub Actions [automatically populate](https://help.github.com/en/articles/virtual-environments-for-github-actions#github_token-secret) a [`GITHUB_TOKEN`](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) environment variable which can be used in Workflows.
|
||||
|
||||
@ -10,7 +10,7 @@ In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and
|
||||
|
||||
[GitHub Actions](https://github.com/features/actions) support [Workflows](https://help.github.com/en/articles/configuring-workflows), allowing to run tests on multiple Node versions and publish a release only when all test pass.
|
||||
|
||||
**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../support/node-version.md).
|
||||
**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../../support/node-version.md).
|
||||
|
||||
### `.github/workflows/release.yml` configuration for Node projects
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## Environment variables
|
||||
|
||||
The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
|
||||
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
|
||||
|
||||
**Note**: Make sure to configure your release branch as [protected](https://docs.gitlab.com/ce/user/project/protected_branches.html) in order for the CI/CD build to access the protected variables.
|
||||
|
||||
@ -10,13 +10,13 @@ The [Authentication](../usage/ci-configuration.md#authentication) environment va
|
||||
|
||||
GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass.
|
||||
|
||||
**Note**: The publish pipeline must run a [Node version that meets our version requirement](../support/node-version.md).
|
||||
**Note**: The publish pipeline must run a [Node version that meets our version requirement](../../support/node-version.md).
|
||||
|
||||
### `.gitlab-ci.yml` configuration for Node projects
|
||||
|
||||
This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
|
||||
|
||||
**Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation.
|
||||
**Note**: The`semantic-release` execution command varies depending on whether 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 if all jobs in the test pipeline are successful
|
||||
@ -50,7 +50,7 @@ publish:
|
||||
|
||||
This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
|
||||
|
||||
**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.
|
||||
**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
|
||||
@ -83,7 +83,7 @@ release:
|
||||
|
||||
### `package.json` configuration
|
||||
|
||||
A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -2,15 +2,15 @@
|
||||
|
||||
## Environment variables
|
||||
|
||||
The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
|
||||
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
|
||||
|
||||
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
|
||||
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
|
||||
|
||||
## Node.js project configuration
|
||||
|
||||
### `Jenkinsfile (Declarative Pipeline)` configuration for a Node.js job
|
||||
|
||||
**Note**: The publish pipeline must run a Node version that [meets our requirement](../support/node-version.md).
|
||||
**Note**: The publish pipeline must run a Node version that [meets our requirement](../../support/node-version.md).
|
||||
|
||||
This example is a minimal configuration for **semantic-release** with a build running a version of Node labelled as "node LTS".
|
||||
Since versions of Node are manually downloaded and labelled, we recommend keeping the version used for the release steps up-to-date with the latest LTS version.
|
||||
@ -50,7 +50,7 @@ pipeline {
|
||||
|
||||
### `package.json` configuration for a Node job
|
||||
|
||||
A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -2,9 +2,9 @@
|
||||
|
||||
## Environment variables
|
||||
|
||||
The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
|
||||
The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
|
||||
|
||||
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
|
||||
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
|
||||
|
||||
## Node.js projects configuration
|
||||
|
||||
@ -12,7 +12,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
|
||||
|
||||
This example is a minimal configuration for **semantic-release** with a build running Node 14 and 16. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
|
||||
|
||||
This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
|
||||
This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
|
||||
|
||||
It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
|
||||
|
||||
@ -43,7 +43,7 @@ jobs:
|
||||
|
||||
### `package.json` configuration for multiple Node jobs
|
||||
|
||||
A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -57,13 +57,13 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins
|
||||
|
||||
For projects that require to be tested with one or multiple version of a Non-JavaScript [language](https://docs.travis-ci.com/user/languages), optionally on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os).
|
||||
|
||||
This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
|
||||
This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
|
||||
|
||||
### `.travis.yml` configuration for non-JavaScript projects
|
||||
|
||||
This example is a minimal configuration for **semantic-release** with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go). See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
|
||||
|
||||
This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
|
||||
This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
|
||||
|
||||
It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
|
||||
|
||||
2
docs/recipes/git-hosted-services/README.md
Normal file
2
docs/recipes/git-hosted-services/README.md
Normal file
@ -0,0 +1,2 @@
|
||||
# Git hosted services
|
||||
- [Git authentication with SSH keys](git-auth-ssh-keys.md)
|
||||
@ -1,6 +1,6 @@
|
||||
# Git authentication with SSH keys
|
||||
|
||||
When using [environment variables](../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../usage/configuration.md#configuration) (the format will be automatically converted as needed).
|
||||
When using [environment variables](../../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../../usage/configuration.md#configuration) (the format will be automatically converted as needed).
|
||||
|
||||
Alternatively the Git repository can be accessed via [SSH](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) by creating SSH keys, adding the public one to your Git hosted account and making the private one available on the CI environment.
|
||||
|
||||
4
docs/recipes/release-workflow/README.md
Normal file
4
docs/recipes/release-workflow/README.md
Normal file
@ -0,0 +1,4 @@
|
||||
# Release workflow
|
||||
- [Publishing on distribution channels](distribution-channels.md)
|
||||
- [Publishing maintenance releases](maintenance-releases.md)
|
||||
- [Publishing pre-releases](pre-releases.md)
|
||||
@ -3,8 +3,8 @@
|
||||
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): `['+([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']`
|
||||
- [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']`
|
||||
|
||||
## Initial release
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
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']`
|
||||
- [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']`
|
||||
|
||||
## Initial release
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
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']`
|
||||
- [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']`
|
||||
|
||||
## Initial release
|
||||
|
||||
@ -47,7 +47,7 @@ To publish a non-Node package (without a `package.json`) you would need to:
|
||||
- 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
|
||||
|
||||
See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
|
||||
See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments.
|
||||
|
||||
In addition, you will need to configure the **semantic-release** [plugins](../usage/plugins.md#plugins) to disable the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin which is used by default and use a plugin for your project type.
|
||||
|
||||
@ -71,7 +71,7 @@ Here is a basic example to create [GitHub releases](https://help.github.com/arti
|
||||
|
||||
**Note**: This is a theoretical example where the command `set-version` update the project version with the value passed as its first argument and `publish-package` publishes the package to a registry.
|
||||
|
||||
See the [package managers and languages recipes](../recipes/README.md#package-managers-and-languages) for more details on specific project types.
|
||||
See the [package managers and languages recipes](../recipes/release-workflow/README.md#package-managers-and-languages) for more details on specific project types.
|
||||
|
||||
## Can I use semantic-release with any CI service?
|
||||
|
||||
@ -79,7 +79,7 @@ Yes, **semantic-release** can be used with any CI service, as long as it provide
|
||||
- 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)
|
||||
|
||||
See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
|
||||
See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments.
|
||||
|
||||
## Can I run semantic-release on my local machine rather than on a CI server?
|
||||
|
||||
@ -95,7 +95,7 @@ However this is not the recommended approach, as running unit and integration te
|
||||
|
||||
Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration.
|
||||
|
||||
See the [GitLab CI recipes](../recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
|
||||
See the [GitLab CI recipes](../recipes/ci-configurations/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
|
||||
|
||||
## Can I use semantic-release with any Git hosted environment?
|
||||
|
||||
@ -194,7 +194,7 @@ If you need more control over the timing of releases, see [Triggering a release]
|
||||
|
||||
This is not supported by **semantic-release** as it's not considered a good practice, mostly because [Semantic Versioning](https://semver.org) rules applies differently to major version zero.
|
||||
|
||||
If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/pre-releases.md#publishing-pre-releases).
|
||||
If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/release-workflow/pre-releases.md#publishing-pre-releases).
|
||||
|
||||
See [“Introduction to SemVer” - Irina Gebauer](https://blog.greenkeeper.io/introduction-to-semver-d272990c44f2) for more details on [Semantic Versioning](https://semver.org) and the recommendation to start at version `1.0.0`.
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ See our [Node Support Policy](node-support-policy.md) for our long-term promise
|
||||
The recommended approach is to run the `semantic-release` command from a CI job running on the latest available LTS version of node.
|
||||
This can either be a job used by your project to test on the latest Node LTS version or a dedicated job for the release steps.
|
||||
|
||||
See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
|
||||
See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details.
|
||||
|
||||
## Alternative solutions
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ Here is a few example of the CI services that can be used to achieve this:
|
||||
- [Wercker Workflows](http://devcenter.wercker.com/docs/workflows)
|
||||
- [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline).
|
||||
|
||||
See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
|
||||
See [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details.
|
||||
|
||||
## Authentication
|
||||
|
||||
@ -29,7 +29,7 @@ See [CI configuration recipes](../recipes/README.md#ci-configurations) for more
|
||||
| `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 clearification `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-auth-ssh-keys.md).
|
||||
Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-hosted-services/git-auth-ssh-keys.md).
|
||||
|
||||
### Authentication for plugins
|
||||
|
||||
@ -44,6 +44,6 @@ See each plugin's documentation for the environment variables required.
|
||||
|
||||
The authentication token/credentials have to be made available in the CI service via environment variables.
|
||||
|
||||
See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
|
||||
See [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
|
||||
|
||||
**Note**: The environment variables `GH_TOKEN`, `GITHUB_TOKEN`, `GL_TOKEN` and `GITLAB_TOKEN` can be used for both the Git authentication and the API authentication required by [@semantic-release/github](https://github.com/semantic-release/github) and [@semantic-release/gitlab](https://github.com/semantic-release/gitlab).
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
- Maintain multiple lines of releases in parallel
|
||||
- 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.
|
||||
See [Release workflow recipes](../recipes/release-workflow/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.
|
||||
@ -108,7 +108,7 @@ A project must define a minimum of 1 release branch and can have a maximum of 3.
|
||||
|
||||
**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.
|
||||
See [publishing on distribution channels recipe](../recipes/release-workflow/distribution-channels.md) for a detailed example.
|
||||
|
||||
#### Pushing to a release branch
|
||||
|
||||
@ -142,7 +142,7 @@ Maintenance branches are always considered lower than [release branches](#releas
|
||||
|
||||
**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 versions within the branch `range` can be merged. If a 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.
|
||||
See [publishing maintenance releases recipe](../recipes/release-workflow/maintenance-releases.md) for a detailed example.
|
||||
|
||||
#### Pushing to a maintenance branch
|
||||
|
||||
@ -171,7 +171,7 @@ A pre-release branch is characterized by the `prerelease` property that defines
|
||||
|
||||
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.
|
||||
See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md) for a detailed example.
|
||||
|
||||
#### Pushing to a pre-release branch
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user