github-semantic-version

Automated semantic version releases powered by Github Issues.

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_TOKENto CI

For example, in Travis CI's "Settings" tab for your project, you'll see:

For your GH_TOKENcreate one in Githubwith repocredentials.

You can find NPM_TOKENin your ~/.npmrcfile:

//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 > Labelssection, 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 gsvsection of package.json, to a gsv.jsonfile, or a .gsvrcfile 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 internalLabelcan 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 labelsto your open PRs:

As these get merged, github-semantic-versionwill use this to determine how to bump the current version. PRs merged without a label will be treated as patchreleases.

If any un-tagged commits are pushed to masteroutside of a PR, they're automatically treated as patchreleases.

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-versionoperates with an additive functionalityphilosophy.

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 masteroutside 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 --changelogflag in your npm scripts).

github-semantic-version --changelog

Append the latest change to an existing CHANGELOG (must have already been generated by the --initflag above).

You'll want to run github-semantic-version --initoutside of CI to generate the initial CHANGELOG before enabling the --changelogflag.

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 --bumpand --changelogare 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 wouldhappen without any writing to files, pushing to Github, or publishing to NPM.

Debug

Prepend DEBUG=github-semantic-version:*to the github-semantic-versioncommand 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 startVersionto the gsvsection 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_TOKENeither.

github

You can add a githubobject to the gsvsection 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 abortOnMissingLabeloption.

{
  "gsv": {
    "abortOnMissingLabel": true
  }
}

addReleasedLabelOnSuccess

Define the addReleasedLabelOnSuccessand releasedLabeloptions to add a label to a PR once it has been successfully published.

{
  "gsv": {
    "releasedLabel": "Released",
    "addReleasedLabelOnSuccess": true
  }
}

The releasedLabeldefaults to "Released".

License

MIT License 2016 © Eric Clemmons

HomePage

https://github.com/ericclemmons/github-semantic-version#readme

Repository

https+https://github.com/ericclemmons/github-semantic-version


上一篇:markdown-it-external-links
下一篇:markdown-it-vanilla-loader

相关推荐

官方社区

扫码加入 JavaScript 社区