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