npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

github-semantic-version

v7.6.0

Published

Automated semantic version releases powered by Github Issues.

Downloads

255

Readme

github-semantic-version

Automated semantic version releases powered by Github Issues.

travis build version downloads MIT License


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:

tokens

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