https://github.com/ericclemmons/github-semantic-version
Automated semantic version releases powered by Github Issues.
https://github.com/ericclemmons/github-semantic-version
Last synced: 10 months ago
JSON representation
Automated semantic version releases powered by Github Issues.
- Host: GitHub
- URL: https://github.com/ericclemmons/github-semantic-version
- Owner: ericclemmons
- License: mit
- Created: 2015-12-29T17:50:41.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2022-12-06T15:30:40.000Z (over 3 years ago)
- Last Synced: 2025-08-14T00:03:28.726Z (10 months ago)
- Language: JavaScript
- Homepage:
- Size: 399 KB
- Stars: 21
- Watchers: 4
- Forks: 8
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# github-semantic-version
> Automated semantic version releases powered by Github Issues.
[](https://travis-ci.org/ericclemmons/github-semantic-version)
[](http://npm.im/github-semantic-version)
[](http://npm-stat.com/charts.html?package=github-semantic-version)
[](http://opensource.org/licenses/MIT)
- - -
## Getting Started
### 1. Install
```shell
$ 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](https://github.com/settings/tokens)
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
```json
{
"gsv": {
"majorLabel": "Version: Major",
"minorLabel": "Version: Minor",
"patchLabel": "Version: Patch"
}
}
```
##### gsv.json or .gsvrc example
```json
{
"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.
```json
{
"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`
```yaml
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`
```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:
```json
{
"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](https://www.npmjs.com/package/github).
```json
{
"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.
```json
{
"gsv": {
"abortOnMissingLabel": true
}
}
```
#### addReleasedLabelOnSuccess
Define the `addReleasedLabelOnSuccess` and `releasedLabel` options to add a label to a PR once it has been successfully published.
```json
{
"gsv": {
"releasedLabel": "Released",
"addReleasedLabelOnSuccess": true
}
}
```
> The `releasedLabel` defaults to "Released".
### License
> MIT License 2016 © Eric Clemmons