master
Usage
Extending
Recipes
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:
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:
1
* feat: initial commit # => v1.0.0 on @latest
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
* feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
| \
3
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
4
| * feat: a feature # => v1.1.0 on @1.x
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
| \
3
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
4
| | \
5
| * | feat: a feature # => v1.1.0 on @1.x
6
| | * fix: a fix # => v1.0.1 on @1.0.x
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
| \
3
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
4
| | \
5
| * | feat: a feature # => v1.1.0 on @1.x
6
| | * fix: a fix # => v1.0.1 on @1.0.x
7
| | /|
8
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
| \
3
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
4
| | \
5
| * | feat: a feature # => v1.1.0 on @1.x
6
| | * fix: a fix # => v1.0.1 on @1.0.x
7
| | /|
8
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
9
| /| |
10
* | | Merge branch 1.x into master # => v2.1.0 on @latest
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
| \
3
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
4
| | \
5
| * | feat: a feature # => v1.1.0 on @1.x
6
| | * fix: a fix # => v1.0.1 on @1.0.x
7
| | /|
8
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
9
| /| |
10
* | | Merge branch 1.x into master # => v2.1.0 on @latest
11
* | | fix: another fix # => v2.1.1 on @latest
Copied!
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:
1
* feat: initial commit # => v1.0.0 on @latest
2
| \
3
* | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
4
| | \
5
| * | feat: a feature # => v1.1.0 on @1.x
6
| | * fix: a fix # => v1.0.1 on @1.0.x
7
| | /|
8
| * | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
9
| /| |
10
* | | Merge branch 1.x into master # => v2.1.0 on @latest
11
* | | fix: another fix # => v2.1.1 on @latest
12
| | |
13
| * | fix: another fix # => v1.1.2 on @1.x
Copied!
Last modified 16d ago
Copy link
Edit on GitHub