node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

kablam

Kablam

Kablam is a tool designed to help with release processes.

What it does

  • kablam --help

    • Displays help.
  • kablam release Prepares a release by merging and tagging branches.

    • Optionally check if the build has succeeded on Jenkins
    • Prompt for new tag name and message
    • Display commits since last release (the last tag), prompt for history file information
    • Update History.md and package.json
    • Creates a release branch which is then merged to master and stable
    • Creates a tag on stable
    • Push code to origin

In almost all prompts (except History file lines), a sensible default is provided.

Configuration

Configuration is done by way of a file in the project root named .kablamrc. Here's a sample file, with basic docs:

{
  /* which tagging style this project uses. Supports "semver", "incremental" and "time" */
  "tagStyle": "semver",
 
  /* The type of branch model in use.
     Supports two styles: 'trunk' and 'git-flow'
  */
  "branchingModel": ["trunk", {
    "trunk": "master"            // which branch you develop upon and tag 
  }],
 
  "branchingModel": ["git-flow", {
    "deployment": "stable",      // the stable release branch 
    "development": "master",     // the main development branch 
    "releasePrefix": "release/"  // the prefix of release branches 
  }],
 
  /* the name of the History file to update */
  "historyFile": "History.md",
 
  /* information about the jenkins job which builds this project. Optional. */
  "jenkins": {
    "host": "http://my.jenkins.server:8080/",
    "job": "my-jenkins-job"
  },
 
  /* path to a file where detailed logs are stored. Logs are truncated to 256kb. Optional. */
  "logFile": ".kablamlog",
 
  /* default tag message. %s is replaced with the tag name. Optional, default shown below */
  "tagMessage": "Version %s",
 
  /* if set to true, the default tag message is always used. The user isn't able to modify it. Default false */
  "fixedTagMessage": false
}

Custom tasks

To add custom tasks to Kablam, write your task and publish it as an NPM module with a name starting with kablam-task-. Namespaced packages are also fine, eg: @sc/kablam-task-deploy. You can then execute this by running kablam @sc/deploy. If you'd like to use a different name for the task, add a property to your .kablamrc file like so:

{
  "taskAliases": {
    "deploy": "@sc/deploy",
    "d": "@sc/deploy"
  }
}

Writing custom tasks

A task should be exported as a function which returns a Promise (something with a .then() method). It should also define a description property, and optionally a preflight function which is executed before running the task. This may return a Promise if asynchronous behaviour is needed; or throw an error to halt the task.

Colors

Three color themes are provided:

  • 'default'
  • 'highcontrast', same as default, but the greys are now white
  • 'mono', no coloring of output.

To choose a theme, set an environment variable called KABLAM_THEME. This can be done in your shell's configuration file (~/.zshrc, etc), or once off like so: kablam_THEME=mono kablam

Development

  • To set up for development, clone the repository and run make
  • To compile source into executable code, run make compile
  • To run the tests, run make test
  • To lint the code, run make lint
  • To create a new tag and publish to npm, run make publish