Installing dependencies.
This commit is contained in:
+6
@@ -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)
|
||||
Generated
Vendored
+49
@@ -0,0 +1,49 @@
|
||||
# Using semantic-release with [CircleCI 2.0 workflows](https://circleci.com/docs/2.0/workflows)
|
||||
|
||||
## 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)..
|
||||
|
||||
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
|
||||
|
||||
### `.circleci/config.yml` configuration for multiple Node jobs
|
||||
|
||||
This example is a minimal configuration for **semantic-release** with tests running against Node 16 and 14.
|
||||
See [CircleCI documentation](https://circleci.com/docs/2.0) for additional configuration options.
|
||||
|
||||
In this example, the [`circleci/node`](https://circleci.com/developer/orbs/orb/circleci/node) orb is imported (Which makes some node operations easier), then a `release` job is defined which will run `semantic-release`.
|
||||
|
||||
To run our `release` job, we have created a workflow named `test_and_release` which will run two jobs, `node/test`, which comes from the node orb and will test our application, and our release job.
|
||||
Here, we are actually making use of [matrix jobs](https://circleci.com/blog/circleci-matrix-jobs/) so that our single `node/test` job will actually be executed twice, once for Node version 16, and once for version 14.
|
||||
Finally, we call our release job with a `requires` parameter so that `release` will run against the latest LTS version of node, only after `node/test` has successfully tested against v14 and v16.
|
||||
|
||||
```yaml
|
||||
version: 2.1
|
||||
orbs:
|
||||
node: circleci/node@5.0.0
|
||||
jobs:
|
||||
release:
|
||||
executor: node/default
|
||||
steps:
|
||||
- checkout
|
||||
- node/install-packages # Install and automatically cache packages
|
||||
# Run optional required steps before releasing
|
||||
# - run: npm run build-script
|
||||
- run: npx semantic-release
|
||||
|
||||
workflows:
|
||||
test_and_release:
|
||||
# Run the test jobs first, then the release only when all the test jobs are successful
|
||||
jobs:
|
||||
- node/test:
|
||||
matrix:
|
||||
parameters:
|
||||
version:
|
||||
- 16.1.0
|
||||
- 14.17.0
|
||||
- release:
|
||||
requires:
|
||||
- node/test
|
||||
```
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
# Using semantic-release with [GitHub Actions](https://help.github.com/en/categories/automating-your-workflow-with-github-actions)
|
||||
|
||||
## 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).
|
||||
|
||||
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.
|
||||
|
||||
## Node project configuration
|
||||
|
||||
[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).
|
||||
|
||||
### `.github/workflows/release.yml` configuration for Node projects
|
||||
|
||||
The following is a minimal configuration for [`semantic-release`](https://github.com/semantic-release/semantic-release) with a build running on the latest LTS version of Node when a new commit is pushed to a `master` branch.
|
||||
See [Configuring a Workflow](https://help.github.com/en/articles/configuring-a-workflow) for additional configuration options.
|
||||
|
||||
```yaml
|
||||
name: Release
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
jobs:
|
||||
release:
|
||||
name: Release
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v2
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v2
|
||||
with:
|
||||
node-version: 'lts/*'
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
- name: Release
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
run: npx semantic-release
|
||||
```
|
||||
|
||||
## Pushing `package.json` changes to a `master` branch
|
||||
|
||||
To keep `package.json` updated in the `master` branch, [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used.
|
||||
|
||||
**Note**: Automatically populated `GITHUB_TOKEN` cannot be used if branch protection is enabled for the target branch. It is **not** advised to mitigate this limitation by overriding an automatically populated `GITHUB_TOKEN` variable with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line), as it poses a security risk. Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant. One can use Personal Access Tokens in trusted environments, where all developers should have the ability to perform administrative actions in the given repository and branch protection is enabled solely for convenience purposes, to remind about required reviews or CI checks.
|
||||
|
||||
If the risk is acceptable, some extra configuration is needed. The [actions/checkout `persist-credentials`](https://github.com/marketplace/actions/checkout#usage) option needs to be `false`, otherwise the generated `GITHUB_TOKEN` will interfere with the custom one. Example:
|
||||
|
||||
```yaml
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v2
|
||||
with:
|
||||
fetch-depth: 0
|
||||
persist-credentials: false # <--- this
|
||||
```
|
||||
|
||||
## 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
|
||||
name: Release
|
||||
on:
|
||||
repository_dispatch:
|
||||
types: [semantic-release]
|
||||
jobs:
|
||||
# ...
|
||||
```
|
||||
|
||||
To trigger a release, call (with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) stored in `GITHUB_TOKEN` environment variable):
|
||||
|
||||
```
|
||||
$ curl -v -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/repos/[org-name-or-username]/[repository]/dispatches -d '{ "event_type": "semantic-release" }'
|
||||
```
|
||||
|
||||
### 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
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
# Using semantic-release with [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd)
|
||||
|
||||
## 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.
|
||||
|
||||
## Node project configuration
|
||||
|
||||
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).
|
||||
|
||||
### `.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.
|
||||
|
||||
```yaml
|
||||
# The release pipeline will run only if all jobs in the test pipeline are successful
|
||||
stages:
|
||||
- test
|
||||
- release
|
||||
|
||||
before_script:
|
||||
- npm install
|
||||
|
||||
node:10:
|
||||
image: node:10
|
||||
stage: test
|
||||
script:
|
||||
- npm test
|
||||
|
||||
node:12:
|
||||
image: node:12
|
||||
stage: test
|
||||
script:
|
||||
- npm test
|
||||
|
||||
publish:
|
||||
image: node:12
|
||||
stage: release
|
||||
script:
|
||||
- npx semantic-release
|
||||
```
|
||||
|
||||
### `.gitlab-ci.yml` configuration for all 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 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:
|
||||
- release
|
||||
|
||||
release:
|
||||
image: node:10-buster-slim
|
||||
stage: release
|
||||
before_script:
|
||||
- apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
|
||||
- npm install -g semantic-release @semantic-release/gitlab
|
||||
script:
|
||||
- semantic-release
|
||||
only:
|
||||
- master
|
||||
|
||||
release:
|
||||
image: node:12-buster-slim
|
||||
stage: release
|
||||
before_script:
|
||||
- apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
|
||||
- npm install -g semantic-release @semantic-release/gitlab
|
||||
script:
|
||||
- semantic-release
|
||||
only:
|
||||
- master
|
||||
```
|
||||
|
||||
### `package.json` configuration
|
||||
|
||||
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
|
||||
```json
|
||||
{
|
||||
"devDependencies": {
|
||||
"semantic-release": "^15.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
# Using semantic-release with [Jenkins CI](https://www.jenkins.io/doc/book/pipeline/)
|
||||
|
||||
## 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/)..
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
See the [Jenkins documentation](https://www.jenkins.io/doc/) for additional configuration options.
|
||||
|
||||
```yaml
|
||||
// The release stage in the pipeline will run only if the test stage in the pipeline is successful
|
||||
pipeline {
|
||||
agent any
|
||||
environment {
|
||||
GH_TOKEN = credentials('some-id')
|
||||
}
|
||||
stages {
|
||||
stage('Test') {
|
||||
steps {
|
||||
sh '''
|
||||
# Configure your test steps here (checkout, npm install, tests etc)
|
||||
npm install
|
||||
npm test
|
||||
'''
|
||||
}
|
||||
}
|
||||
stage('Release') {
|
||||
tools {
|
||||
nodejs "node LTS"
|
||||
}
|
||||
steps {
|
||||
sh '''
|
||||
# Run optional required steps before releasing
|
||||
npx semantic-release
|
||||
'''
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `package.json` configuration for a Node job
|
||||
|
||||
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
|
||||
```json
|
||||
{
|
||||
"devDependencies": {
|
||||
"semantic-release": "^18.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
# Using semantic-release with [Travis CI](https://travis-ci.org)
|
||||
|
||||
## 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).
|
||||
|
||||
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
|
||||
|
||||
### `.travis.yml` configuration for multiple Node.js jobs
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
**Note**: It's not recommended to run the `semantic-release` command in the Travis `script` step as each script in this step will be executed regardless of the outcome of the previous one. See [travis-ci/travis-ci#1066](https://github.com/travis-ci/travis-ci/issues/1066).
|
||||
|
||||
**Advanced configuration**: Running the tests in the `script` step of the `release` stage is not necessary as the previous stage(s) already ran them. To increase speed, the `script` step of the `release` stage can be overwritten to skip the tests. Note that other commands such as build or compilation might still be required.
|
||||
|
||||
```yaml
|
||||
language: node_js
|
||||
|
||||
node_js:
|
||||
- 14
|
||||
- 16
|
||||
|
||||
jobs:
|
||||
include:
|
||||
# Define the release stage that runs semantic-release
|
||||
- stage: release
|
||||
node_js: lts/*
|
||||
# Advanced: optionally overwrite your default `script` step to skip the tests
|
||||
# script: skip
|
||||
deploy:
|
||||
provider: script
|
||||
skip_cleanup: true
|
||||
script:
|
||||
- npx semantic-release
|
||||
```
|
||||
|
||||
### `package.json` configuration for multiple Node jobs
|
||||
|
||||
A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
|
||||
|
||||
```json
|
||||
{
|
||||
"devDependencies": {
|
||||
"semantic-release": "^18.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Non-Node.js projects configuration
|
||||
|
||||
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.
|
||||
|
||||
### `.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).
|
||||
|
||||
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.
|
||||
|
||||
**Note**: It's not recommended to run the `semantic-release` command in the Travis `script` step as each script in this step will be executed regardless of the outcome of the previous one. See [travis-ci/travis-ci#1066](https://github.com/travis-ci/travis-ci/issues/1066).
|
||||
|
||||
**Advanced configuration**: Running the tests in the `script` step of the `release` stage is not necessary as the previous stage(s) already ran them. To increase speed, the `script` step of the `release` stage can be overwritten to skip the tests. Note that other commands such as build or compilation might still be required.
|
||||
|
||||
```yaml
|
||||
language: go
|
||||
|
||||
go:
|
||||
- 1.6
|
||||
- 1.7
|
||||
|
||||
jobs:
|
||||
include:
|
||||
# Define the release stage that runs semantic-release
|
||||
- stage: release
|
||||
# Advanced: optionally overwrite your default `script` step to skip the tests
|
||||
# script:
|
||||
# - make
|
||||
deploy:
|
||||
provider: script
|
||||
skip_cleanup: true
|
||||
script:
|
||||
# Use nvm to install and use the Node LTS version (nvm is installed on all Travis images)
|
||||
- nvm install lts/*
|
||||
- npx semantic-release
|
||||
on:
|
||||
all_branches: true
|
||||
```
|
||||
+2
@@ -0,0 +1,2 @@
|
||||
# Git hosted services
|
||||
- [Git authentication with SSH keys](git-auth-ssh-keys.md)
|
||||
Generated
Vendored
+163
@@ -0,0 +1,163 @@
|
||||
# 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).
|
||||
|
||||
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.
|
||||
|
||||
**Note:** SSH keys allow to push the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated to the released version. Some plugins might also require an API token. See each plugin documentation for additional information.
|
||||
|
||||
## Generating the SSH keys
|
||||
|
||||
In your local repository root:
|
||||
|
||||
```bash
|
||||
$ ssh-keygen -t rsa -b 4096 -C "<your_email>" -f git_deploy_key -N "<ssh_passphrase>"
|
||||
```
|
||||
|
||||
`your_email` must be the email associated with your Git hosted account. `ssh_passphrase` must be a long and hard to guess string. It will be used later.
|
||||
|
||||
This will generate a public key in `git_deploy_key.pub` and a private key in `git_deploy_key`.
|
||||
|
||||
## 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
|
||||
|
||||
Open the `git_deploy_key.pub` file (public key) and copy the entire content.
|
||||
|
||||
In GitHub **Settings**, click on **SSH and GPG keys** in the sidebar, then on the **New SSH Key** button.
|
||||
|
||||
Paste the entire content of `git_deploy_key.pub` file (public key) and click the **Add SSH Key** button.
|
||||
|
||||
Delete the `git_deploy_key.pub` file:
|
||||
|
||||
```bash
|
||||
$ rm git_deploy_key.pub
|
||||
```
|
||||
|
||||
See [Adding a new SSH key to your GitHub account](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/) for more details.
|
||||
|
||||
## Adding the SSH private key to the CI environment
|
||||
|
||||
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)
|
||||
|
||||
### Adding the SSH private key to Travis CI
|
||||
|
||||
Install the [Travis CLI](https://github.com/travis-ci/travis.rb#installation):
|
||||
|
||||
```bash
|
||||
$ gem install travis
|
||||
```
|
||||
|
||||
[Login](https://github.com/travis-ci/travis.rb#login) to Travis with the CLI:
|
||||
|
||||
```bash
|
||||
$ travis login
|
||||
```
|
||||
|
||||
Add the [environment](https://github.com/travis-ci/travis.rb#env) variable `SSH_PASSPHRASE` to Travis with the value set during the [SSH keys generation](#generating-the-ssh-keys) step:
|
||||
|
||||
```bash
|
||||
$ travis env set SSH_PASSPHRASE <ssh_passphrase>
|
||||
```
|
||||
|
||||
[Encrypt](https://github.com/travis-ci/travis.rb#encrypt) the `git_deploy_key` (private key) using a symmetric encryption (AES-256), and store the secret in a secure environment variable in the Travis environment:
|
||||
|
||||
```bash
|
||||
$ travis encrypt-file git_deploy_key
|
||||
```
|
||||
|
||||
The `travis encrypt-file` will encrypt the private key into the `git_deploy_key.enc` file and output in the console the command to add to your `.travis.yml` file. It should look like `openssl aes-256-cbc -K $encrypted_KKKKKKKKKKKK_key -iv $encrypted_VVVVVVVVVVVV_iv -in git_deploy_key.enc -out git_deploy_key -d`.
|
||||
|
||||
Copy this command to your `.travis.yml` file in the `before_install` step. Change the output path to write the unencrypted key in `/tmp`: `-out git_deploy_key` => `/tmp/git_deploy_key`. This will avoid to commit / modify / delete the unencrypted key by mistake on the CI. Then add the commands to decrypt the ssh private key and make it available to `git`:
|
||||
|
||||
```yaml
|
||||
before_install:
|
||||
# Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
|
||||
- openssl aes-256-cbc -K $encrypted_KKKKKKKKKKKK_key -iv $encrypted_VVVVVVVVVVVV_iv -in git_deploy_key.enc -out /tmp/git_deploy_key -d
|
||||
# Make sure only the current user can read the private key
|
||||
- chmod 600 /tmp/git_deploy_key
|
||||
# Create a script to return the passphrase environment variable to ssh-add
|
||||
- echo 'echo ${SSH_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
|
||||
# Start the authentication agent
|
||||
- eval "$(ssh-agent -s)"
|
||||
# Add the key to the authentication agent
|
||||
- DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
|
||||
```
|
||||
|
||||
See [Encrypting Files](https://docs.travis-ci.com/user/encrypting-files) for more details.
|
||||
|
||||
Delete the local private key as it won't be used anymore:
|
||||
|
||||
```bash
|
||||
$ rm git_deploy_key
|
||||
```
|
||||
|
||||
Commit the encrypted private key and the `.travis.yml` file to your repository:
|
||||
|
||||
```bash
|
||||
$ git add git_deploy_key.enc .travis.yml
|
||||
$ git commit -m "ci(travis): Add the encrypted private ssh key"
|
||||
$ 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*:
|
||||
|
||||
```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`
|
||||
salt=SSSSSSSSSSSSSSSS
|
||||
key=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
|
||||
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.
|
||||
|
||||
Then add to your `.circleci/config.yml` the commands to decrypt the ssh private key and make it available to `git`:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
jobs:
|
||||
coverage_test_publish:
|
||||
# docker, working_dir, etc
|
||||
steps:
|
||||
- run:
|
||||
# Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
|
||||
- openssl aes-256-cbc -d -K $REPO_ENC_KEY -iv $REPO_ENC_IV -in git_deploy_key.enc -out /tmp/git_deploy_key
|
||||
# Make sure only the current user can read the private key
|
||||
- chmod 600 /tmp/git_deploy_key
|
||||
# Create a script to return the passphrase environment variable to ssh-add
|
||||
- echo 'echo ${SSL_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
|
||||
# Start the authentication agent
|
||||
- eval "$(ssh-agent -s)"
|
||||
# Add the key to the authentication agent
|
||||
- DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
|
||||
# checkout, restore_cache, run: yarn install, save_cache, etc.
|
||||
# Run semantic-release after all the above is set.
|
||||
```
|
||||
|
||||
The unencrypted key is written to `/tmp` to avoid to commit / modify / delete the unencrypted key by mistake on the CI environment.
|
||||
|
||||
Delete the local private key as it won't be used anymore:
|
||||
|
||||
```bash
|
||||
$ rm git_deploy_key
|
||||
```
|
||||
|
||||
Commit the encrypted private key and the `.circleci/config.yml` file to your repository:
|
||||
|
||||
```bash
|
||||
$ git add git_deploy_key.enc .circleci/config.yml
|
||||
$ git commit -m "ci(circle): Add the encrypted private ssh key"
|
||||
$ git push
|
||||
```
|
||||
+4
@@ -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)
|
||||
Generated
Vendored
+116
@@ -0,0 +1,116 @@
|
||||
# Publishing on distribution channels
|
||||
|
||||
This recipe will walk you through a simple example that uses distribution channels to make releases available only to a subset of users, in order to collect feedbacks before distributing the release to all users.
|
||||
|
||||
This example uses the **semantic-release** default configuration:
|
||||
- [branches](../../usage/configuration.md#branches): `['+([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
|
||||
|
||||
We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
|
||||
|
||||
The Git history of the repository is:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
```
|
||||
|
||||
## Releasing a bug fix
|
||||
|
||||
We can now continue to commit changes and release updates to our users. For example we can commit a bug fix with the message `fix: a fix` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* fix: a fix # => v1.0.1 on @latest
|
||||
```
|
||||
|
||||
## Releasing a feature on next
|
||||
|
||||
We now want to develop an important feature, which is a breaking change. Considering the scope of this feature we want to make it available, at first, only to our most dedicated users in order to get feedback. Once we get that feedback we can make improvements and ultimately make the new feature available to all users.
|
||||
|
||||
To implement that workflow we can create the branch `next` and commit our feature to this branch. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@next`. That means only the users installing our module with `npm install example-module@next` will receive the version `2.0.0`. Other users installing with `npm install example-module` will still receive the version `1.0.1`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* fix: a fix # => v1.0.1 on @latest
|
||||
| \
|
||||
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|
||||
```
|
||||
|
||||
## Releasing a bug fix on next
|
||||
|
||||
One of our users starts to use the new `2.0.0` release and reports a bug. We develop a bug fix and commit it to the `next` branch with the message `fix: fix something on the big feature`. When pushing that commit, **semantic-release** will release the version `2.0.1` on the dist-tag `@next`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* fix: a fix # => v1.0.1 on @latest
|
||||
| \
|
||||
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|
||||
| * fix: fix something on the big feature # => v2.0.1 on @next
|
||||
```
|
||||
|
||||
## Releasing a feature on latest
|
||||
|
||||
We now want to develop a smaller, non-breaking feature. Its scope is small enough that we don't need to have a phase of feedback and we can release it to all users right away.
|
||||
|
||||
If we were to commit that feature on `next` only a subset of users would get it, and we would need to wait for the end of our feedback period in order to make both the big and the small feature available to all users.
|
||||
|
||||
Instead, we develop that small feature commit it to `master` with the message `feat: a small feature`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@latest` so all users can benefit from it right away.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* fix: a fix # => v1.0.1 on @latest
|
||||
| \
|
||||
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|
||||
| * fix: fix something on the big feature # => v2.0.1 on @next
|
||||
* | feat: a small feature # => v1.1.0 on @latest
|
||||
```
|
||||
|
||||
## Porting a feature to next
|
||||
|
||||
Most of our users now have access to the small feature, but we still need to make it available to our users using the `@next` dist-tag. To do so we need to merge our changes made on `master` (the commit `feat: a small feature`) into `next`. As `master` and `next` branches have diverged, this merge might require to resolve conflicts.
|
||||
|
||||
Once the conflicts are resolved and the merge commit is pushed to `next`, **semantic-release** will release the version `2.1.0` on the dist-tag `@next` which contains both our small and big feature.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* fix: a fix # => v1.0.1 on @latest
|
||||
| \
|
||||
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|
||||
| * fix: fix something on the big feature # => v2.0.1 on @next
|
||||
* | feat: a small feature # => v1.1.0 on @latest
|
||||
| * Merge branch master into next # => v2.1.0 on @next
|
||||
```
|
||||
|
||||
## Adding a version to latest
|
||||
|
||||
After a period of feedback from our users using the `@next` dist-tag we feel confident to make our big feature available to all users. To do so we merge the `next` branch into `master`. There should be no conflict as `next` is strictly ahead of `master`.
|
||||
|
||||
Once the merge commit is pushed to `master`, **semantic-release** will add the version `2.1.0` to the dist-tag `@latest` so all users will receive it when installing out module with `npm install example-module`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* fix: a fix # => v1.0.1 on @latest
|
||||
| \
|
||||
| * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|
||||
| * fix: fix something on the big feature # => v2.0.1 on @next
|
||||
* | feat: a small feature # => v1.1.0 on @latest
|
||||
| * Merge branch master into next # => v2.1.0 on @next
|
||||
| /|
|
||||
* | Merge branch next into master # => v2.1.0 on @latest
|
||||
```
|
||||
|
||||
We can now continue to push new fixes and features on `master`, or a new breaking change on `next` as we did before.
|
||||
Generated
Vendored
+156
@@ -0,0 +1,156 @@
|
||||
# Publishing maintenance releases
|
||||
|
||||
This recipe will walk you through a simple example that uses Git branches and distribution channels to publish fixes and features for old versions of a package.
|
||||
|
||||
This example uses the **semantic-release** default configuration:
|
||||
- [branches](../../usage/configuration.md#branches): `['+([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
|
||||
|
||||
We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit`. When pushing that commit, on `master` **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
|
||||
|
||||
The Git history of the repository is:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
```
|
||||
|
||||
## Releasing a breaking change
|
||||
|
||||
We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change.
|
||||
|
||||
We commit that change with the message `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required` to `master`. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
* feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
```
|
||||
|
||||
## Releasing a feature for version 1.x users
|
||||
|
||||
One of our users request a new feature, however they cannot migrate to Node.js 8 or higher due to corporate policies.
|
||||
|
||||
If we were to push that feature on `master` and release it, the new version would require Node.js 8 or higher as the release would also contain the commit `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
|
||||
|
||||
Instead, we create the branch `1.x` from the tag `v1.0.0` with the command `git checkout -b 1.x v1.0.0` and we commit that feature with the message `feat: a feature` to the branch `1.x`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@release-1.x` so users who can't migrate to Node.js 8 or higher can benefit from it.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
| * feat: a feature # => v1.1.0 on @1.x
|
||||
```
|
||||
|
||||
## Releasing a bug fix for version 1.0.x users
|
||||
|
||||
Another user currently using version `1.0.0` reports a bug. They cannot migrate to Node.js 8 or higher and they also cannot migrate to `1.1.0` as they do not use the feature developed in `feat: a feature` and their corporate policies require to go through a costly quality assurance process for each `minor` upgrades.
|
||||
|
||||
In order to deliver the bug fix in a `patch` release, we create the branch `1.0.x` from the tag `v1.0.0` with the command `git checkout -b 1.0.x v1.0.0` and we commit that fix with the message `fix: a fix` to the branch `1.0.x`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@release-1.0.x` so users who can't migrate to `1.1.x` or `2.x` can benefit from it.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
| | \
|
||||
| * | feat: a feature # => v1.1.0 on @1.x
|
||||
| | * fix: a fix # => v1.0.1 on @1.0.x
|
||||
```
|
||||
|
||||
## Porting a bug fix from 1.0.x to 1.x
|
||||
|
||||
Now that we have released a fix in version `1.0.1` we want to make it available to `1.1.x` users as well.
|
||||
|
||||
To do so we need to merge the changes made on `1.0.x` (the commit `fix: a fix`) into the `1.x` branch. As `1.0.x` and `1.x` branches have diverged, this merge might require to resolve conflicts.
|
||||
|
||||
Once the conflicts are resolved and the merge commit is pushed to the branch `1.x`, **semantic-release** will release the version `1.1.1` on the dist-tag `@release-1.x` which contains both our feature and bug fix.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
| | \
|
||||
| * | feat: a feature # => v1.1.0 on @1.x
|
||||
| | * fix: a fix # => v1.0.1 on @1.0.x
|
||||
| | /|
|
||||
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
|
||||
```
|
||||
|
||||
## Porting bug fixes and features to master
|
||||
|
||||
Finally we want to make both our feature and bug fix available to users using the `@latest` dist-tag.
|
||||
|
||||
To do so we need to merge the changes made on `1.x` (the commits `feat: a feature` and `fix: a fix`) into `master`. As `1.x` and `master` branches have diverged, this merge might require to resolve conflicts.
|
||||
|
||||
Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `2.1.0` on the dist-tag `@latest` which now contains the breaking change feature, the feature and the bug fix.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
| | \
|
||||
| * | feat: a feature # => v1.1.0 on @1.x
|
||||
| | * fix: a fix # => v1.0.1 on @1.0.x
|
||||
| | /|
|
||||
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
|
||||
| /| |
|
||||
* | | Merge branch 1.x into master # => v2.1.0 on @latest
|
||||
```
|
||||
|
||||
## Releasing a bug fix for version 2.1.0 users
|
||||
|
||||
One of our users using the version `2.1.0` version reports a bug.
|
||||
|
||||
We can simply commit the bug fix with the message `fix: another fix` to `master`. When pushing that commit, **semantic-release** will release the version `2.1.1` on the dist-tag `@latest`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
| | \
|
||||
| * | feat: a feature # => v1.1.0 on @1.x
|
||||
| | * fix: a fix # => v1.0.1 on @1.0.x
|
||||
| | /|
|
||||
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
|
||||
| /| |
|
||||
* | | Merge branch 1.x into master # => v2.1.0 on @latest
|
||||
* | | fix: another fix # => v2.1.1 on @latest
|
||||
```
|
||||
|
||||
## Porting a bug fix from master to 1.x
|
||||
|
||||
The bug fix `fix: another fix` also affects version `1.1.1` users, so we want to port it to the `1.x` branch.
|
||||
|
||||
To do so we need to cherry pick our fix commit made on `master` (`fix: another fix`) into `1.x` with `git checkout 1.x && git cherry-pick <sha of fix: another fix>`. As `master` and `1.x` branches have diverged, the cherry picking might require to resolve conflicts.
|
||||
|
||||
Once the conflicts are resolved and the commit is pushed to `1.x`, **semantic-release** will release the version `1.1.2` on the dist-tag `@release-1.x` which contains `feat: a feature`, `fix: a fix` and `fix: another fix` but not `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|
||||
| | \
|
||||
| * | feat: a feature # => v1.1.0 on @1.x
|
||||
| | * fix: a fix # => v1.0.1 on @1.0.x
|
||||
| | /|
|
||||
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
|
||||
| /| |
|
||||
* | | Merge branch 1.x into master # => v2.1.0 on @latest
|
||||
* | | fix: another fix # => v2.1.1 on @latest
|
||||
| | |
|
||||
| * | fix: another fix # => v1.1.2 on @1.x
|
||||
```
|
||||
+196
@@ -0,0 +1,196 @@
|
||||
# Publishing pre-releases
|
||||
|
||||
This recipe will walk you through a simple example that uses pre-releases to publish beta versions while working on a future major release and then make only one release on the default distribution.
|
||||
|
||||
This example uses the **semantic-release** default configuration:
|
||||
- [branches](../../usage/configuration.md#branches): `['+([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
|
||||
|
||||
We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit`. When pushing that commit, on `master` **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
|
||||
|
||||
The Git history of the repository is:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
```
|
||||
|
||||
## Working on a future release
|
||||
|
||||
We now decide to work on a future major release, which will be composed of multiple features, some of them being breaking changes. We want to publish our package for each new feature developed for test purpose, however we do not want to increment our package version or make it available to our users until all the features are developed and tested.
|
||||
|
||||
To implement that workflow we can create the branch `beta` and commit our first feature there. When pushing that commit, **semantic-release** will publish the pre-release version `2.0.0-beta.1` on the dist-tag `@beta`. That allow us to run integration tests by installing our module with `npm install example-module@beta`. Other users installing with `npm install example-module` will still receive the version `1.0.0`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
```
|
||||
|
||||
We can continue to work on our future release by committing and pushing other features or bug fixes on the `beta` branch. With each push, **semantic-release** will publish a new pre-release on the dist-tag `@beta`, which allow us to run our integration tests.
|
||||
|
||||
With another feature, the Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
```
|
||||
|
||||
## Releasing a bug fix on the default distribution channel
|
||||
|
||||
In the meantime we can also continue to commit changes and release updates to our users.
|
||||
|
||||
For example, we can commit a bug fix with the message `fix: a fix` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
```
|
||||
|
||||
## Working on another future release
|
||||
|
||||
We now decide to work on another future major release, in parallel of the beta one, which will also be composed of multiple features, some of them being breaking changes.
|
||||
|
||||
To implement that workflow we can create the branch `alpha` from the branch `beta` and commit our first feature there. When pushing that commit, **semantic-release** will publish the pre-release version `3.0.0-alpha.1` on the dist-tag `@alpha`. That allow us to run integration tests by installing our module with `npm install example-module@alpha`. Other users installing with `npm install example-module` will still receive the version `1.0.0`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
| | \
|
||||
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|
||||
```
|
||||
|
||||
We can continue to work on our future release by committing and pushing other features or bug fixes on the `alpha` branch. With each push, **semantic-release** will publish a new pre-release on the dist-tag `@alpha`, which allow us to run our integration tests.
|
||||
|
||||
With another feature, the Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
| | \
|
||||
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|
||||
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
|
||||
```
|
||||
|
||||
## Publishing the 2.0.0 beta release to the default distribution channel
|
||||
|
||||
Once we've developed and pushed all the feature we want to include in the future version `2.0.0` in the `beta` branch and all our tests are successful we can release it to our users.
|
||||
|
||||
To do so we need to merge our changes made on `beta` into `master`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
|
||||
|
||||
Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
| | \
|
||||
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|
||||
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
|
||||
| /| |
|
||||
* | | Merge branch beta into master # => v2.0.0 on @latest
|
||||
```
|
||||
|
||||
## Publishing the 3.0.0 alpha release to the beta distribution channel
|
||||
|
||||
Now that we published our the version `2.0.0` that was previously in beta, we decide to promote the version `3.0.0` in alpha to beta.
|
||||
|
||||
To do so we need to merge our changes made on `alpha` into `beta`. There should be no conflict as `alpha` is strictly ahead of `master`.
|
||||
|
||||
Once the merge commit is pushed to `beta`, **semantic-release** will publish the pre-release version `3.0.0-beta.1` on the dist-tag `@beta`, which allow us to run our integration tests.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
| | \
|
||||
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|
||||
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
|
||||
| /| |
|
||||
* | | Merge branch beta into master # => v2.0.0 on @latest
|
||||
| | /|
|
||||
| * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
|
||||
```
|
||||
|
||||
## Publishing the 3.0.0 beta release to the default distribution channel
|
||||
|
||||
Once we've developed and pushed all the feature we want to include in the future version `3.0.0` in the `beta` branch and all our tests are successful we can release it to our users.
|
||||
|
||||
To do so we need to merge our changes made on `beta` into `master`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
|
||||
|
||||
Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `3.0.0` on the dist-tag `@latest`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
| | \
|
||||
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|
||||
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
|
||||
| /| |
|
||||
* | | Merge branch beta into master # => v2.0.0 on @latest
|
||||
| | /|
|
||||
| * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
|
||||
| /| |
|
||||
* | | Merge branch beta into master # => v3.0.0 on @latest
|
||||
```
|
||||
|
||||
## Working on a third future release
|
||||
|
||||
We can now start to work on a new future major release, version `4.0.0`, on the `@beta` distribution channel.
|
||||
|
||||
To do so we first need to update the `beta` branch with all the changes from `master` (the commits `fix: a fix`). As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
|
||||
|
||||
We can now commit our new feature on `beta`. When pushing that commit, **semantic-release** will publish the pre-release version `3.1.0-beta.1` on the dist-tag `@beta`. That allow us to run integration tests by installing our module with `npm install example-module@beta`. Other users installing with `npm install example-module` will still receive the version `3.0.0`.
|
||||
|
||||
The Git history of the repository is now:
|
||||
|
||||
```
|
||||
* feat: initial commit # => v1.0.0 on @latest
|
||||
| \
|
||||
| * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|
||||
| * feat: second feature # => v2.0.0-beta.2 on @beta
|
||||
* | fix: a fix # => v1.0.1 on @latest
|
||||
| | \
|
||||
| | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|
||||
| | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
|
||||
| /| |
|
||||
* | | Merge branch beta into master # => v2.0.0 on @latest
|
||||
| | /|
|
||||
| * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
|
||||
| /| |
|
||||
* | | Merge branch beta into master # => v3.0.0 on @latest
|
||||
| \| |
|
||||
| * | Merge branch master into beta
|
||||
| * | feat: new feature # => v3.1.0-beta.1 on @beta
|
||||
```
|
||||
Reference in New Issue
Block a user