Awesome
github-semantic-version
Automated semantic version releases powered by Github Issues.
Getting Started
1. Install
$ npm install --save-dev github-semantic-version
2. Add GH_TOKEN
& NPM_TOKEN
to CI
For example, in Travis CI's "Settings" tab for your project, you'll see:
For your GH_TOKEN
create one in Github
with repo
credentials.
You can find NPM_TOKEN
in your ~/.npmrc
file:
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
Once these are in place, your new versions can be pushed back to Github & NPM without permissions & security issues.
3. Create labels
From your repo's Issues > Labels
section, add three labels representing the major, minor, and patch level changes in your repo. Ex:
- "Version: Major"
- "Version: Minor"
- "Version: Patch"
Add your label definitions to a gsv
section of package.json
, to a gsv.json
file, or a .gsvrc
file in the base directory of your project.
package.json example
{
"gsv": {
"majorLabel": "Version: Major",
"minorLabel": "Version: Minor",
"patchLabel": "Version: Patch"
}
}
gsv.json or .gsvrc example
{
"majorLabel": "Version: Major",
"minorLabel": "Version: Minor",
"patchLabel": "Version: Patch"
}
Non-version Labels
Sometimes a PR should not increment and publish a new version, for example, when updating dependencies, tests, or docs. To support
this, a 4th label named internalLabel
can be used. When this label is found on a PR, it will be skipped.
{
"gsv": {
"majorLabel": "Version: Major",
"minorLabel": "Version: Minor",
"patchLabel": "Version: Patch",
"internalLabel": "No version: Internal"
}
}
4. Add labels to issues
Add one of your custom defined labels to your open PRs:
As these get merged, github-semantic-version
will use this to determine
how to bump the current version. PRs merged without a label will be treated
as patch
releases.
If any un-tagged commits are pushed to master
outside of a PR, they're
automatically treated as patch
releases.
5. Update .travis.yml
sudo: false
language: node_js
cache:
directories:
- node_modules
notifications:
email: false
branches:
except:
- /^v[0-9]/
deploy:
provider: script
script: npm run release
skip_cleanup: true
on:
branch: master
6. Usage
As automation related to your code and publishing to the world can sometimes be scary, github-semantic-version
operates with an additive functionality philosophy.
Options
github-semantic-version
Displays the usage information.
github-semantic-version --bump
Update the package version, no CHANGELOG, don't push to Github, don't publish to NPM.
Meant to be used in a CI environment.
github-semantic-version --init
Generates a fresh CHANGELOG based on labeled PRs and any commits to master
outside
of any PR. Also calculates the package version based on those PRs and commits. Won't push to Github or publish to NPM.
Meant to be used outside of a CI environment to generate the initial CHANGELOG.
The expected workflow here is to ensure parity between the calculated version/changelog and your current repo version. Once that happens, you'll
want to manually commit those changes (adding github-semantic-version as a dependency, the new npm scripts to run on CI success, the CHANGELOG,
updated package.json, etc.) to master (or merge a labeled PR). Once CI builds successfully, these additions will be noted in the CHANGELOG (assuming
that you specified the --changelog
flag in your npm scripts).
github-semantic-version --changelog
Append the latest change to an
existing CHANGELOG (must have already been generated by the --init
flag above).
You'll want to run github-semantic-version --init
outside of CI to generate the initial CHANGELOG
before enabling the --changelog
flag.
github-semantic-version --bump --changelog
Bump the version and append the latest change to the CHANGELOG.
github-semantic-version --bump --changelog --push
Bump the version, append the latest change to the CHANGELOG, and push the changes to Github.
github-semantic-version --bump --changelog --push --publish
Bump the version, append the latest change to the CHANGELOG, push to Github, and publish to NPM.
Other flags
--force
The flags --bump
and --changelog
are meant to be used in a CI environment. Override this if you know what you're doing.
--dry-run
Append this to see output of what would happen without any writing to files, pushing to Github, or publishing to NPM.
Debug
Prepend DEBUG=github-semantic-version:*
to the github-semantic-version
command to show all debug output when running.
7. Update package.json
{
"scripts": {
"prerelease": "npm run build",
"release": "github-semantic-version --bump --changelog --push --publish"
}
}
startVersion
You can add a startVersion
to the gsv
section of package.json
(or to gsv.json
) that will be used as the starting point to
calculate the package version of a repo. Ex:
{
"gsv": {
"startVersion": "2.5.0",
"majorLabel": "Version: Major"
}
}
If you're working on a private project, you can leave out --publish
, which
means you have no need for your NPM_TOKEN
either.
github
You can add a github
object to the gsv
section of package.json
(or to gsv.json
),
which are options that will be passed to the Github API.
{
"gsv": {
"github": {
"host": "github.my-GHE-enabled-company.com"
}
}
}
abortOnMissingLabel
By default, all PRs without a label will default to "patch". If you'd prefer to skip the PR instead of releasing, use the abortOnMissingLabel
option.
{
"gsv": {
"abortOnMissingLabel": true
}
}
addReleasedLabelOnSuccess
Define the addReleasedLabelOnSuccess
and releasedLabel
options to add a label to a PR once it has been successfully published.
{
"gsv": {
"releasedLabel": "Released",
"addReleasedLabelOnSuccess": true
}
}
The
releasedLabel
defaults to "Released".
License
MIT License 2016 © Eric Clemmons