node-circleci-autorelease

Autorelease your node packages.

• tag
• branch
• gh-pages
• npm publish

It looks up the latest commit log and extracts release name.

git commit -m 'release 1.2.3'
git push origin master

CircleCI creates tag 1.2.3.

You can add and remove files for release tag via hooks.

installation

Just run the following command on your Node.js project.

npm install --save-dev node-circleci-autorelease

install cli for global (optional)

Use nca-cli for omitting $(npm bin)/.

npm install -g nca-cli

This tiny module calls local nca command without absolute path (e.g. $(npm bin)/).

As nca-cli itself doesn't contain node-circleci-autorelease, you don't have to consider about version inconsistencies.

Notice: the following sample commands call global nca.

If you skip installing nca-cli, attach $(npm bin)/ before nca command.

usage

1. initializing

nca init

Two setting files will be generated.

1. .autorelease.yml: config file.
2. .releaseignore: files/patterns to be ignored in release. The same format as .gitignore.

You can set current node version with --node option.

nca init --node

2. generate circle.yml

nca generate

It creates circle.yml to your current working directory for auto-release.

3. commit and push it

Push to master branch with a specific commit message.

git commit -m 'release X.Y.Z'
git push origin master

Then, CircleCI detects the commit message pattern and creates a tag X.Y.Z (See version-bumping for automated commit.)

configuration

Edit .autorelease.yml. It will show below format.

hooks:
  gh_pages:
    pre:
      - npm run generate-doc
config:
  version_prefix: v
  create_gh_pages: true
  create_gh_pages: doc
circle:
  machine:
    environment:
      node:
        version: 6.2.0

There are three fields in this format.

• config: config fields
• hooks: hook commands
• circle: totally compatible with circle.yml

config field

| key | description | default | | :--------------- | :---------------------------------- | :------------------- | | git_user_name | user name of the release commit | CircleCI | | git_user_email | user email of the release commit | [email protected] | | npm_update_depth | --depth option to "npm update" | 0 ( = no run) | | version_prefix | prefix of tags to be created | v | | create_branch | create release branch or not | false | | npm_shrinkwrap | run "npm shrinkwrap" before release | false | | create_gh_pages | create gh-pages branch or not | false | | gh_pages_dir | directory to publish on gh-pages | (null) |

npm_update_depth

node-circleci-autorelease tries to update node_modules via npm update everytime after npm install. npm_update_depth config is the depth of the update. By default, 0 is set and npm update will never occur.

config:
  npm_update_depth: 3

version_prefix

To release v1.2.3, you should set

config:
  version_prefix: v

at your .autorelease.yml and make a commit with message

release 1.2.3

npm_shrinkwrap

node-circleci-autorelease tries to fix all the node_modules versions before release by the executed ones using npm shrinkwrap. To enable this function,

config:
  shrinkwrap: true

gh-pages configuration

To release gh-pages branch, you should set

config:
  create_gh_pages: true
  gh_pages_dir: doc

If gh_pages_dir is set, only the directory is hosted.

example

---
config:
  git_user_name: shinout
  git_user_email: [email protected]
  npm_update_depth: 5
  version_prefix: v
  create_branch: true
  npm_shrinkwrap: true
  create_gh_pages: true
  gh_pages_dir: doc

hooks field

You can register commands before/after the following events.

• update_modules: before/after running npm update
• release: before/after releasing process
• gh_pages: before/after creating gh-pages branch
• bmp: before/after bumping (in nca bmp command)

Each section must have "pre" or "post" section containing a command or list of commands.

example

1. Convert ES6+ files in src to dist using babel

---
hooks:
  update_modules:
    post:
        - babel src -d dist

2. Add timestamp

---
hooks:
  release:
    pre: date "+%s" > timestamp

3. Add documentation files before release using documentationjs

---
hooks:
  gh_pages:
    pre: documentation build --format html -o doc src/**/*

circle field

Write your custom circle.yml setting here. Don't write circle.yml directory, nca generate command will generate it automatically.

example

---
circle:
  general:
    branches:
      ignore:
        - xxx
  machine:
    environment:
      ABC: 123
  dependencies:
    post:
      - npm run xxx

.releaseignore file

Files/patterns to be ignored in release. Format is the same as .gitignore.

example

# dot files
.*

# npm https://www.npmjs.com
node_modules

# documentations
/doc

# source files
/src

# test files
/test

# development tools
/tools

# CircleCI cetting https://circleci.com
circle.yml

# debug logs
*.log

version bumping

node-circleci-autorelease can bump versions with version-bumping tools. Two bumping tools are available.

• bmp: kt3k/bmp.
• bmp: januswel/yangpao.

gem install bmp

or

go get github.com/januswel/yangpao

usage

nca bmp p
nca bmp m
nca bmp j
nca bmp r

They update version and commit with a message except running nca bmp r. These commands also update circle.yml automatically. --skipCircle or its alias -s option skips updating circle.yml.

nca bmp p --skipCircle

re-release

nca bmp r doesn't bump version. Instead, it makes an empty commit with the following message:

re-release X.Y.Z

where X.Y.Z is the current version. This is useful when the last release is failed.

This feature is disabled by default.

bmp hooks

hooks:
  bmp:
    pre:
      - echo "bmp start"
    post:
      - echo "bmp end"

You can set bumping hooks in .autorelease.yml.

npm publish

Enable publishing your project by setting two environment variables at CircleCI.

NPM_AUTH  # "_auth" of your .npmrc
NPM_EMAIL # "email" of your .npmrc

then CircleCI automatically runs npm publish.

DRY RUN

DRY_RUN=1 nca

JavaScript API

Run command with args.

es6+

import {run} from 'node-circleci-autorelease'
nca.run(['bmp', 'p', '-s'])

commonjs

var nca = require('node-circleci-autorelease')
nca.run(['bmp', 'p', '-s'])

Note that 2nd argument should be

LICENSE

MIT