README
pr-bumper
Use text from a pull request description to automatically bump the version number of a project upon merge.
pr-bumper performs three main tasks:
- Check if an open pull request has the appropriate version bump scope in its description.
- Update the version of
package.jsonwhen a pull request is merged based on the scope from the pull request. - Create a tag of the new version after the bump commit.
There are also a number of additional tasks that can be enabled by setting the appropriate values in .pr-bumper.json
See below for more info on the available optional features.
Pull Requests
pr-bumper uses Semantic Versioning.
Pull request descriptions must include a directive indicating the scope of the change being made
(major/minor/patch/none). Directives are case insensitive and wrapped in # to avoid a description such as
Fixing a major bug in the code
being considered a major change.
We also support the aliases of breaking, feature, and fix.
In addition, pre-release tags on versions are supported, but only for the patch or none scope. When using
minor or major with a pre-release tag, the pre-release tag will be cleared.
NOTE pr-bumper never introduces a pre-release tag, it only supports an existing pre-release tag. If you want
to use a pre-release tag, you'll need to add it manually to the version in your package.json as part of your PR,
then pr-bumper will be able to do a patch bump to increment the last number in the pre-release for you.
| Starting Version | Directive | Ending Version |
|---|---|---|
| 1.2.3 | #none# |
1.2.3 |
| 1.2.3-alpha.4 | #none# |
1.2.3-alpha.4 |
| 1.2.3 | #patch# or #fix# |
1.2.4 |
| 1.2.3-alpha.4 | #patch# or #fix# |
1.2.3-alpha.5 |
| 1.2.3-a.b.9 | #patch# or #fix# |
1.2.3-a.b.10 |
| 1.2.3 | #minor# or #feature# |
1.3.0 |
| 1.2.3-alpha.4 | #minor# or #feature# |
1.3.0 |
| 1.2.3 | #major# or #breaking# |
2.0.0 |
| 1.2.3-alpha.4 | #major# or #breaking# |
2.0.0 |
GFM Checklist support
You may also specify a list of possible scopes in a GFM checklist Example:
This project uses semver, please check the scope of this pr:
- #none# - documentation fixes and/or test additions
- #patch# - backwards-compatible bug fix
- #minor# - adding functionality in a backwards-compatible manner
- #major# - incompatible API change
Combined with Pull Request Templates, contributors who are unfamiliar with pr-bumper
will know exactly what to do before the build fails.
Integrations
pr-bumper currently supports pull requests on GitHub, Bitbucket, and Bitbucket Server
It is also optimized to work with Travis CI out-of-the box, but can be configured to work with
TeamCity or Bamboo as well using the .pr-bumper.json config file.
Installation
npm install -g pr-bumper@^3.0.0
The specific version range is important so that you don't pick up a breaking major version bump without meaning to, for example in your CI script.
Usage
You can check for the existence of a valid directive in the current (open) pr (during the pr build) by using
pr-bumper check
If you set config.features.coverage.enabled to true in your .pr-bumper.json, you can compare your current code
coverage against the saved baseline in package.json by using:
pr-bumper check-coverage
NOTE You must wait until after your tests have run to perform the above check, or there will be no new coverage info for
pr-bumperto check against the baseline.
You can perform the automated bump in the merge build by using:
pr-bumper bump
Configuration
If you're using Travis CI and public GitHub, pr-bumper will probably work well for you out-of-the-box. However, you
can create a .pr-bumper.json file at the root of your repository to override any of the defaults.
Here are the defaults that are provided by pr-bumper and can be overwritten by defining them in your own
.pr-bumper.json file:
{
"ci": {
"env": {
"branch": "TRAVIS_BRANCH",
"buildNumber": "TRAVIS_BUILD_NUMBER",
"pr": "TRAVIS_PULL_REQUEST",
"repoSlug": "TRAVIS_REPO_SLUG"
},
"gitUser": {
"email": "travis.ci.ciena@gmail.com",
"name": "Travis CI"
},
"provider": "travis"
},
"features": {
"changelog": {
"enabled": false,
"file": "CHANGELOG.md"
},
"comments": {
"enabled": false
},
"compliance": {
"enabled": false,
"production": false,
"output": {
"requirementsFile": "js-requirements.json",
"reposFile": "repos",
"ignoreFile": "ignore"
},
"additionalRepos": []
},
"coverage": {
"enabled": false,
"file": "coverage/coverage-summary.json"
},
"dependencies": {
"enabled": false,
"snapshotFile": "dependency-snapshot.json"
},
"maxScope": {
"enabled": false,
"value": "major"
},
"logging": {
"enabled": false,
"file": "pr-bumper-log.json"
}
},
"vcs": {
"domain": "github.com",
"env": {
"readToken": "RO_GH_TOKEN",
"writeToken": "GITHUB_TOKEN",
"username": "",
"password": ""
},
"provider": "github",
"repository": {
"name": "",
"owner": ""
}
}
}
You'll notice the data in .pr-bumper.json is separated into three top-level properties, ci, features and vcs.
ci and vcs help pr-bumper work with your particular environment, while features
allows you to enable and configure optional features within pr-bumper.
ci
Holds all the information pr-bumper needs to interact with your continuous integration system.
ci.env
Defines the names of the environment variables that pr-bumper needs to find out information about the current build.
ci.env.branch
The name of the environment variable that holds the current branch being built (on a merge build) or the target branch of a pull request (on a pr build).
The default is TRAVIS_BRANCH which is already set in Travis CI.
If you're using a provider of teamcity, you'll want to specify your own value here (e.g. TEAMCITY_BRANCH).
Don't forget you'll need to update your build step in TeamCity to set the variable as well:
export TEAMCITY_BRANCH="%teamcity.build.branch%"
ci.env.buildNumber
The name of the environment variable that holds the number of the current build.
The default is TRAVIS_BUILD_NUMBER which is already set in Travis CI.
If you're using a provider of teamcity, you'll want to specify your own value here (e.g. TEAMCITY_BUILD_NUMBER)
Don't forget you'll need to update your build step in TeamCity to set the variable as well:
export TEAMCITY_BUILD_NUMBER="%teamcity.build.id%"
ci.env.pr
The name of the environment variable that holds the number of the pull request (on a pr build) or false (on a
merge build)
The default is TRAVIS_PULL_REQUEST which is already set in Travis CI.
If you're using a provider of teamcity or bamboo, you'll want to specify your own value here (e.g. TEAMCITY_PULL_REQUEST)
Don't forget you'll need to update your build step in TeamCity to set the variable as well:
stripped_branch=\$(echo "%teamcity.build.branch%" | sed -e "s/\/merge//")
re='^[0-9]+