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

automatic-release

v1.1.1

Published

Automates the full release process for Open Source projects on GitHub, using Travis CI and deploying to NPM.

Downloads

882

Readme

automatic-release

Automates the release process for GitHub projects.

npm version dependency status travis ci build status Codecov Known Vulnerabilities license

What it does

Creating and managing projects on GitHub usually requires lots of time and effort. When developing libraries, in particular, the tasks required for publishing new releases are often very long, complex, and error-prone.

Meet automatic-release, a NodeJS-based command line tool which makes new library releases "a matter of a single click", allowing developers to focus on the important things - developing! automatic-release achieves that by automating the whole release process. This includes

  • incrementing version numbers,
  • generating changelogs,
  • creating Git tags,
  • and creating GitHub releases.

Once following the Git Flow branching model and the Angular Git Commit Conventions as well as using a Continuous Integration platform such as Travis CI, publishing a new library release to NPM & GitHub gets as simple as merging the latest develop state into the master branch.

Automatic Release Preview

How to install

You can get automatic-release via npm by either adding it as a new devDependency to your package.json file and running npm install, or running the following command:

npm install automatic-release --save-dev

Requirements

  • automatic-release requires at least NodeJS 7.6 (or higher). Earlier 7.x versions of NodeJS (7.0 to 7.5) might also work when executing automatic-release using the --harmony-async-await flag.

  • automatic-release expects a package.json and a CHANGELOG.md file at the project root. Further on, the package.json file should at least contain a package name, a version, and a valid GitHub repository URL.

How to use

Following the (Angular) Git Commit Convention

Internally, automatic-release analyzes the commit history in order to evaluate version numbers and generate changelogs. To make this work, developers must follow a specific convention when making commits. Such a commit convention usually describes the structure and naming of the commit message (type, scope, message), the commit body (further details), and the commit footer (breaking changes, issues this commit fixes).

As of now, automatic-release expects the Angular Commit Message Format to be used. For more details, read the full Angular Commit Message Guidelines. In short, commits following this convention look like the following:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Quick Tip: I personally do not recommend forcing developers to follow this convention for every single commit, as this might lead to less commits being made in general. Instead, it's probably better to squash commits when merging PRs, and then only name the PR merge commit after the naming convention.

Using Git Flow

Moreover, following the Git Flow branching model is highly recommended. To summarize, Git Flow proposes a number of branch types such as the master branch (containing the latest release), the develop branch (as the "master during development"), and multiple feature & bugfix branches (enabling developers to work in parallel). For more details, continue reading at A successful Git branching model.

Utilizing this concept simplifies the release management significantly (amongst further advantages it has for the overall development workflow). However, automatic-release does not require all the branches Git Flow proposes to exist. It only expects the following two branches to exist and get used correctly:

  • the master branch, containing the latest (published) release
  • the develop branch as the main development branch

Quick Tip: Makde the develop branch the project's default branch so that Pull Requests are always opened against develop and not master.

Integration with Travis CI

Step 1: Setup repository for Travis CI

First of all, setup Travis CI for your GitHub repository by

  • connecting your Travis CI account to your GitHub account,
  • enabling the GitHub repository for Travis CI,
  • and having a .travis.yml configuration file set up.

For further details on how to setup Travis CI, continue reading the official Travis CI - Getting Started guide.

Step 2: Add environment variables

Within Travis CI, select your GitHub project, go to More Options / Settings and make sure the following Environment Variables are defined:

GH_TOKEN: This environment variable defines the GitHub Access Token, enabling automatic-release to push commits and tags to GitHub as well as create GitHub releases.

To generate this token, visit your GitHub - Personal Access Tokens page, click Generate new token, select (at least) the repo / public_repo scope access and finish up by hitting Generate token.

NPM_TOKEN: This environment variable defines the NPM Authentication Token, needed by Travis CI to deploy your library to the public NPM registry.

Getting this token is as simple as logging into your NPM account locally and copying the authToken from your .npmrc file. A detailed instruction can be found right here.

FORCE_COLOR: This environment variable (forcefully) enables colorful logging output when set to 1. If the automatic-release logging output is black'n'white only this variable might help.

Step 3: Extend Travis CI configuration file

Finally, setup the automated release process by extending the .travis.yml configuration file. First, make sure bothh the master and develop branches are included in the branches block. For example:

branches:
  only:
    - master
    - develop

Next, add automatic-release to the scripts block of your package.json file to make it available to npm run commands:

{
  "scripts": {
    "automatic-release": "automatic-release"
  }
}

Then, define a new Travis CI job for releases containing (at least) the following commands (replace <...> with actual data):

jobs:
  include:
    - stage: release
      before_install:
        # Clone the whole repository because we also need the develop branch for releasing
        - git clone "https://github.com/$TRAVIS_REPO_SLUG.git" "$TRAVIS_REPO_SLUG";
        - cd "$TRAVIS_REPO_SLUG";
        - git checkout -qf "$TRAVIS_COMMIT";
        #  Fix Travis CI issue of detached heads in git
        - git checkout master
      install:
        # ...
      script:
        # ...
      before_deploy:
        # Login to Git to be able to make commits (required by automatic-release)
        - git config --global user.name "<GITHUB-USER-NAME>"; # REPLACE!
        - git config --global user.email "<GITHUB-USER-EMAIL>"; # REPLACE!
        - git config credential.helper "store --file=.git/credentials";
        - echo "https://$GH_TOKEN:@github.com" > .git/credentials;
        # Run automatic-release
        - npm run automatic-release
      deploy:
        provider: npm
        email: <NPM_USER_EMAIL> # REPLACE!
        api_key: "$NPM_TOKEN"
        skip_cleanup: true

If you plan to publish from a directory other than the root, don't forget to navigate into the folder in the before_deploy section. Also, you might need to copy the updated package.json and CHANGELOG.md file into your publish directory after running automatic-release yet before running the npm deploy.

Finally, use the release job defined above in your stages with the master branch condition:

stages:
  - name: release
    if: branch = master

Creator

Dominique Müller