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