semantic-release 25.0.5 → 25.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +36 -30
  2. package/bin/semantic-release.js +1 -1
  3. package/index.d.ts +3 -0
  4. package/lib/definitions/errors.js +53 -33
  5. package/lib/git.js +13 -11
  6. package/lib/hide-sensitive.js +14 -1
  7. package/lib/verify.js +4 -0
  8. package/package.json +20 -15
  9. package/docs/README.md +0 -7
  10. package/docs/developer-guide/README.md +0 -5
  11. package/docs/developer-guide/js-api.md +0 -294
  12. package/docs/developer-guide/plugin.md +0 -284
  13. package/docs/developer-guide/shareable-configuration.md +0 -1
  14. package/docs/extending/README.md +0 -4
  15. package/docs/extending/plugins-list.md +0 -233
  16. package/docs/extending/shareable-configurations-list.md +0 -22
  17. package/docs/recipes/ci-configurations/README.md +0 -7
  18. package/docs/recipes/ci-configurations/circleci-workflows.md +0 -49
  19. package/docs/recipes/ci-configurations/github-actions.md +0 -136
  20. package/docs/recipes/ci-configurations/gitlab-ci.md +0 -98
  21. package/docs/recipes/ci-configurations/jenkins-ci.md +0 -61
  22. package/docs/recipes/ci-configurations/travis.md +0 -97
  23. package/docs/recipes/git-hosted-services/README.md +0 -3
  24. package/docs/recipes/git-hosted-services/git-auth-ssh-keys.md +0 -166
  25. package/docs/recipes/release-workflow/README.md +0 -5
  26. package/docs/recipes/release-workflow/distribution-channels.md +0 -117
  27. package/docs/recipes/release-workflow/maintenance-releases.md +0 -157
  28. package/docs/recipes/release-workflow/pre-releases.md +0 -197
  29. package/docs/support/FAQ.md +0 -253
  30. package/docs/support/README.md +0 -7
  31. package/docs/support/git-version.md +0 -4
  32. package/docs/support/node-support-policy.md +0 -21
  33. package/docs/support/node-version.md +0 -38
  34. package/docs/support/resources.md +0 -22
  35. package/docs/support/troubleshooting.md +0 -70
  36. package/docs/usage/README.md +0 -9
  37. package/docs/usage/ci-configuration.md +0 -50
  38. package/docs/usage/configuration.md +0 -206
  39. package/docs/usage/getting-started.md +0 -8
  40. package/docs/usage/installation.md +0 -51
  41. package/docs/usage/plugins.md +0 -105
  42. package/docs/usage/shareable-configurations.md +0 -7
  43. package/docs/usage/workflow-configuration.md +0 -199
@@ -1,97 +0,0 @@
1
- # Using semantic-release with [Travis CI](https://travis-ci.org)
2
-
3
- ## Environment variables
4
-
5
- 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).
6
-
7
- Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
8
-
9
- ## Node.js projects configuration
10
-
11
- ### `.travis.yml` configuration for multiple Node.js jobs
12
-
13
- 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.
14
-
15
- 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).
16
-
17
- 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.
18
-
19
- **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).
20
-
21
- **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.
22
-
23
- ```yaml
24
- language: node_js
25
-
26
- node_js:
27
- - 14
28
- - 16
29
-
30
- jobs:
31
- include:
32
- # Define the release stage that runs semantic-release
33
- - stage: release
34
- node_js: lts/*
35
- # Advanced: optionally overwrite your default `script` step to skip the tests
36
- # script: skip
37
- deploy:
38
- provider: script
39
- skip_cleanup: true
40
- script:
41
- - npx semantic-release
42
- ```
43
-
44
- ### `package.json` configuration for multiple Node jobs
45
-
46
- A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
47
-
48
- ```json
49
- {
50
- "devDependencies": {
51
- "semantic-release": "^18.0.0"
52
- }
53
- }
54
- ```
55
-
56
- ## Non-Node.js projects configuration
57
-
58
- 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).
59
-
60
- 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.
61
-
62
- ### `.travis.yml` configuration for non-JavaScript projects
63
-
64
- 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.
65
-
66
- 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).
67
-
68
- 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.
69
-
70
- **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).
71
-
72
- **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.
73
-
74
- ```yaml
75
- language: go
76
-
77
- go:
78
- - 1.6
79
- - 1.7
80
-
81
- jobs:
82
- include:
83
- # Define the release stage that runs semantic-release
84
- - stage: release
85
- # Advanced: optionally overwrite your default `script` step to skip the tests
86
- # script:
87
- # - make
88
- deploy:
89
- provider: script
90
- skip_cleanup: true
91
- script:
92
- # Use nvm to install and use the Node LTS version (nvm is installed on all Travis images)
93
- - nvm install lts/*
94
- - npx semantic-release
95
- on:
96
- all_branches: true
97
- ```
@@ -1,3 +0,0 @@
1
- # Git hosted services
2
-
3
- - [Git authentication with SSH keys](git-auth-ssh-keys.md)
@@ -1,166 +0,0 @@
1
- # Git authentication with SSH keys
2
-
3
- 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).
4
-
5
- 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.
6
-
7
- **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.
8
-
9
- ## Generating the SSH keys
10
-
11
- In your local repository root:
12
-
13
- ```bash
14
- $ ssh-keygen -t rsa -b 4096 -C "<your_email>" -f git_deploy_key -N "<ssh_passphrase>"
15
- ```
16
-
17
- `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.
18
-
19
- This will generate a public key in `git_deploy_key.pub` and a private key in `git_deploy_key`.
20
-
21
- ## Adding the SSH public key to the Git hosted account
22
-
23
- Step by step instructions are provided for the following Git hosted services:
24
-
25
- - [GitHub](#adding-the-ssh-public-key-to-github)
26
-
27
- ### Adding the SSH public key to GitHub
28
-
29
- Open the `git_deploy_key.pub` file (public key) and copy the entire content.
30
-
31
- In GitHub **Settings**, click on **SSH and GPG keys** in the sidebar, then on the **New SSH Key** button.
32
-
33
- Paste the entire content of `git_deploy_key.pub` file (public key) and click the **Add SSH Key** button.
34
-
35
- Delete the `git_deploy_key.pub` file:
36
-
37
- ```bash
38
- $ rm git_deploy_key.pub
39
- ```
40
-
41
- 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.
42
-
43
- ## Adding the SSH private key to the CI environment
44
-
45
- 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.
46
-
47
- Step by step instructions are provided for the following environments:
48
-
49
- - [Travis CI](#adding-the-ssh-private-key-to-travis-ci)
50
- - [Circle CI](#adding-the-ssh-private-key-to-circle-ci)
51
-
52
- ### Adding the SSH private key to Travis CI
53
-
54
- Install the [Travis CLI](https://github.com/travis-ci/travis.rb#installation):
55
-
56
- ```bash
57
- $ gem install travis
58
- ```
59
-
60
- [Login](https://github.com/travis-ci/travis.rb#login) to Travis with the CLI:
61
-
62
- ```bash
63
- $ travis login
64
- ```
65
-
66
- 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:
67
-
68
- ```bash
69
- $ travis env set SSH_PASSPHRASE <ssh_passphrase>
70
- ```
71
-
72
- [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:
73
-
74
- ```bash
75
- $ travis encrypt-file git_deploy_key
76
- ```
77
-
78
- 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`.
79
-
80
- 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`:
81
-
82
- ```yaml
83
- before_install:
84
- # Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
85
- - openssl aes-256-cbc -K $encrypted_KKKKKKKKKKKK_key -iv $encrypted_VVVVVVVVVVVV_iv -in git_deploy_key.enc -out /tmp/git_deploy_key -d
86
- # Make sure only the current user can read the private key
87
- - chmod 600 /tmp/git_deploy_key
88
- # Create a script to return the passphrase environment variable to ssh-add
89
- - echo 'echo ${SSH_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
90
- # Start the authentication agent
91
- - eval "$(ssh-agent -s)"
92
- # Add the key to the authentication agent
93
- - DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
94
- ```
95
-
96
- See [Encrypting Files](https://docs.travis-ci.com/user/encrypting-files) for more details.
97
-
98
- Delete the local private key as it won't be used anymore:
99
-
100
- ```bash
101
- $ rm git_deploy_key
102
- ```
103
-
104
- Commit the encrypted private key and the `.travis.yml` file to your repository:
105
-
106
- ```bash
107
- $ git add git_deploy_key.enc .travis.yml
108
- $ git commit -m "ci(travis): Add the encrypted private ssh key"
109
- $ git push
110
- ```
111
-
112
- ### Adding the SSH private key to Circle CI
113
-
114
- 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_:
115
-
116
- ```bash
117
- $ 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`
118
- salt=SSSSSSSSSSSSSSSS
119
- key=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
120
- iv =VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV
121
- ```
122
-
123
- Add the following [environment variables](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app) to Circle CI:
124
-
125
- - `SSL_PASSPHRASE` - the value set during the [SSH keys generation](#generating-the-ssh-keys) step.
126
- - `REPO_ENC_KEY` - the `key` (KKK) value from the `openssl` step above.
127
- - `REPO_ENC_IV` - the `iv` (VVV) value from the `openssl` step above.
128
-
129
- Then add to your `.circleci/config.yml` the commands to decrypt the ssh private key and make it available to `git`:
130
-
131
- ```yaml
132
- version: 2
133
- jobs:
134
- coverage_test_publish:
135
- # docker, working_dir, etc
136
- steps:
137
- - run:
138
- # Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
139
- - openssl aes-256-cbc -d -K $REPO_ENC_KEY -iv $REPO_ENC_IV -in git_deploy_key.enc -out /tmp/git_deploy_key
140
- # Make sure only the current user can read the private key
141
- - chmod 600 /tmp/git_deploy_key
142
- # Create a script to return the passphrase environment variable to ssh-add
143
- - echo 'echo ${SSL_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
144
- # Start the authentication agent
145
- - eval "$(ssh-agent -s)"
146
- # Add the key to the authentication agent
147
- - DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
148
- # checkout, restore_cache, run: yarn install, save_cache, etc.
149
- # Run semantic-release after all the above is set.
150
- ```
151
-
152
- The unencrypted key is written to `/tmp` to avoid to commit / modify / delete the unencrypted key by mistake on the CI environment.
153
-
154
- Delete the local private key as it won't be used anymore:
155
-
156
- ```bash
157
- $ rm git_deploy_key
158
- ```
159
-
160
- Commit the encrypted private key and the `.circleci/config.yml` file to your repository:
161
-
162
- ```bash
163
- $ git add git_deploy_key.enc .circleci/config.yml
164
- $ git commit -m "ci(circle): Add the encrypted private ssh key"
165
- $ git push
166
- ```
@@ -1,5 +0,0 @@
1
- # Release workflow
2
-
3
- - [Publishing on distribution channels](distribution-channels.md)
4
- - [Publishing maintenance releases](maintenance-releases.md)
5
- - [Publishing pre-releases](pre-releases.md)
@@ -1,117 +0,0 @@
1
- # Publishing on distribution channels
2
-
3
- This recipe will walk you through a simple example that uses distribution channels to make releases available only to a subset of users, in order to collect feedback before distributing the release to all users.
4
-
5
- This example uses the **semantic-release** default configuration:
6
-
7
- - [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
8
- - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
9
-
10
- ## Initial release
11
-
12
- 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` or `main`. 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.
13
-
14
- The Git history of the repository is:
15
-
16
- ```
17
- * feat: initial commit # => v1.0.0 on @latest
18
- ```
19
-
20
- ## Releasing a bug fix
21
-
22
- 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` or `main`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
23
-
24
- The Git history of the repository is now:
25
-
26
- ```
27
- * feat: initial commit # => v1.0.0 on @latest
28
- * fix: a fix # => v1.0.1 on @latest
29
- ```
30
-
31
- ## Releasing a feature on next
32
-
33
- 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.
34
-
35
- 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`.
36
-
37
- The Git history of the repository is now:
38
-
39
- ```
40
- * feat: initial commit # => v1.0.0 on @latest
41
- * fix: a fix # => v1.0.1 on @latest
42
- | \
43
- | * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
44
- ```
45
-
46
- ## Releasing a bug fix on next
47
-
48
- 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`.
49
-
50
- The Git history of the repository is now:
51
-
52
- ```
53
- * feat: initial commit # => v1.0.0 on @latest
54
- * fix: a fix # => v1.0.1 on @latest
55
- | \
56
- | * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
57
- | * fix: fix something on the big feature # => v2.0.1 on @next
58
- ```
59
-
60
- ## Releasing a feature on latest
61
-
62
- 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.
63
-
64
- 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.
65
-
66
- Instead, we develop that small feature commit it to `master` or `main` 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.
67
-
68
- The Git history of the repository is now:
69
-
70
- ```
71
- * feat: initial commit # => v1.0.0 on @latest
72
- * fix: a fix # => v1.0.1 on @latest
73
- | \
74
- | * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
75
- | * fix: fix something on the big feature # => v2.0.1 on @next
76
- * | feat: a small feature # => v1.1.0 on @latest
77
- ```
78
-
79
- ## Porting a feature to next
80
-
81
- 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` or `main` (the commit `feat: a small feature`) into `next`. As `master`/`main` and `next` branches have diverged, this merge might require to resolve conflicts.
82
-
83
- 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.
84
-
85
- The Git history of the repository is now:
86
-
87
- ```
88
- * feat: initial commit # => v1.0.0 on @latest
89
- * fix: a fix # => v1.0.1 on @latest
90
- | \
91
- | * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
92
- | * fix: fix something on the big feature # => v2.0.1 on @next
93
- * | feat: a small feature # => v1.1.0 on @latest
94
- | * Merge branch master/main into next # => v2.1.0 on @next
95
- ```
96
-
97
- ## Adding a version to latest
98
-
99
- 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`/`main`. There should be no conflict as `next` is strictly ahead of `master`/`main`.
100
-
101
- Once the merge commit is pushed to `master`/`main`, **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`.
102
-
103
- The Git history of the repository is now:
104
-
105
- ```
106
- * feat: initial commit # => v1.0.0 on @latest
107
- * fix: a fix # => v1.0.1 on @latest
108
- | \
109
- | * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
110
- | * fix: fix something on the big feature # => v2.0.1 on @next
111
- * | feat: a small feature # => v1.1.0 on @latest
112
- | * Merge branch master/main into next # => v2.1.0 on @next
113
- | /|
114
- * | Merge branch next into master/main # => v2.1.0 on @latest
115
- ```
116
-
117
- We can now continue to push new fixes and features on `master`/`main`, or a new breaking change on `next` as we did before.
@@ -1,157 +0,0 @@
1
- # Publishing maintenance releases
2
-
3
- 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.
4
-
5
- This example uses the **semantic-release** default configuration:
6
-
7
- - [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
8
- - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
9
-
10
- ## Initial release
11
-
12
- 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`/`main` **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.
13
-
14
- The Git history of the repository is:
15
-
16
- ```
17
- * feat: initial commit # => v1.0.0 on @latest
18
- ```
19
-
20
- ## Releasing a breaking change
21
-
22
- We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change.
23
-
24
- We commit that change with the message `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required` to `master`/`main`. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
25
-
26
- The Git history of the repository is now:
27
-
28
- ```
29
- * feat: initial commit # => v1.0.0 on @latest
30
- * feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
31
- ```
32
-
33
- ## Releasing a feature for version 1.x users
34
-
35
- One of our users request a new feature, however they cannot migrate to Node.js 8 or higher due to corporate policies.
36
-
37
- If we were to push that feature on `master`/`main` 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`.
38
-
39
- 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.
40
-
41
- The Git history of the repository is now:
42
-
43
- ```
44
- * feat: initial commit # => v1.0.0 on @latest
45
- | \
46
- * | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
47
- | * feat: a feature # => v1.1.0 on @1.x
48
- ```
49
-
50
- ## Releasing a bug fix for version 1.0.x users
51
-
52
- 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.
53
-
54
- 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.
55
-
56
- The Git history of the repository is now:
57
-
58
- ```
59
- * feat: initial commit # => v1.0.0 on @latest
60
- | \
61
- * | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
62
- | | \
63
- | * | feat: a feature # => v1.1.0 on @1.x
64
- | | * fix: a fix # => v1.0.1 on @1.0.x
65
- ```
66
-
67
- ## Porting a bug fix from 1.0.x to 1.x
68
-
69
- 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.
70
-
71
- 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.
72
-
73
- 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.
74
-
75
- The Git history of the repository is now:
76
-
77
- ```
78
- * feat: initial commit # => v1.0.0 on @latest
79
- | \
80
- * | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
81
- | | \
82
- | * | feat: a feature # => v1.1.0 on @1.x
83
- | | * fix: a fix # => v1.0.1 on @1.0.x
84
- | | /|
85
- | * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
86
- ```
87
-
88
- ## Porting bug fixes and features to master/main
89
-
90
- Finally we want to make both our feature and bug fix available to users using the `@latest` dist-tag.
91
-
92
- To do so we need to merge the changes made on `1.x` (the commits `feat: a feature` and `fix: a fix`) into `master`/`main`. As `1.x` and `master`/`main` branches have diverged, this merge might require to resolve conflicts.
93
-
94
- Once the conflicts are resolved and the merge commit is pushed to `master` or `main`, **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.
95
-
96
- The Git history of the repository is now:
97
-
98
- ```
99
- * feat: initial commit # => v1.0.0 on @latest
100
- | \
101
- * | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
102
- | | \
103
- | * | feat: a feature # => v1.1.0 on @1.x
104
- | | * fix: a fix # => v1.0.1 on @1.0.x
105
- | | /|
106
- | * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
107
- | /| |
108
- * | | Merge branch 1.x into master/main # => v2.1.0 on @latest
109
- ```
110
-
111
- ## Releasing a bug fix for version 2.1.0 users
112
-
113
- One of our users using the version `2.1.0` version reports a bug.
114
-
115
- We can simply commit the bug fix with the message `fix: another fix` to `master`/`main`. When pushing that commit, **semantic-release** will release the version `2.1.1` on the dist-tag `@latest`.
116
-
117
- The Git history of the repository is now:
118
-
119
- ```
120
- * feat: initial commit # => v1.0.0 on @latest
121
- | \
122
- * | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
123
- | | \
124
- | * | feat: a feature # => v1.1.0 on @1.x
125
- | | * fix: a fix # => v1.0.1 on @1.0.x
126
- | | /|
127
- | * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
128
- | /| |
129
- * | | Merge branch 1.x into master/main # => v2.1.0 on @latest
130
- * | | fix: another fix # => v2.1.1 on @latest
131
- ```
132
-
133
- ## Porting a bug fix from master/main to 1.x
134
-
135
- The bug fix `fix: another fix` also affects version `1.1.1` users, so we want to port it to the `1.x` branch.
136
-
137
- To do so we need to cherry pick our fix commit made on `master`/`main` (`fix: another fix`) into `1.x` with `git checkout 1.x && git cherry-pick <sha of fix: another fix>`. As `master`/`main` and `1.x` branches have diverged, the cherry picking might require to resolve conflicts.
138
-
139
- 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`.
140
-
141
- The Git history of the repository is now:
142
-
143
- ```
144
- * feat: initial commit # => v1.0.0 on @latest
145
- | \
146
- * | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
147
- | | \
148
- | * | feat: a feature # => v1.1.0 on @1.x
149
- | | * fix: a fix # => v1.0.1 on @1.0.x
150
- | | /|
151
- | * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
152
- | /| |
153
- * | | Merge branch 1.x into master/main # => v2.1.0 on @latest
154
- * | | fix: another fix # => v2.1.1 on @latest
155
- | | |
156
- | * | fix: another fix # => v1.1.2 on @1.x
157
- ```