Generate release note pages from git commit history.
It's preferable to install it globally through
npm install -g kraken-release-notes
The basic usage is
cd <your_git_project> kraken-release-notes <since>..<until> <template>
<since>..<until>specifies the range of commits as in
git log, see gitrevisions(7)
<template>is an ejs template file used to generate the release notes
Three sample templates are included as a reference in the
This for example is the release notes generated for
joyent/node by running
kraken-release-notes v0.9.8..v0.9.9 html > changelog.html
The second parameter of
kraken-release-notes can be any path to a valid ejs template files.
Several template variables are made available to the script running inside the template.
commits is an array of commits, each containing
sha1commit hash (%H)
authorNameauthor name (%an)
authorEmailauthor email (%ae)
authorDateauthor date (%aD)
committerNamecommitter name (%cn)
committerEmailcommitter email (%ce)
committerDatecommitter date (%cD)
messageLinesarray of body lines (%b)
options the object documented below. Useful for parsing the repository name. See the html-bootstrap for sample usage.
request is an instance of sync-request. This can be useful for querying the Jira API for example to extract extra metadata about a ticket related to a commit.
templateData is an object parsed as JSON that is passed through to the template and can contain any arbitary data as required by the template. Useful for using the same template across different repositories.
Command Line Options
More advanced command line options are
pathGit project path, defaults to the current working path
branchGit branch, defaults to
titleRegular expression to parse the commit title (see next chapter)
meaningMeaning of capturing block in title's regular expression
fileJSON configuration file. This is a better option when you don't want to pass all parameters to the command line, for an example see options.json
templateDataJSON data file that is passed straight through to the template. Path should be relative to current working directory.
Some projects might have special naming conventions for the commit title.
m allow to specify this logic and extract additional information from the title.
For instance, Aria Templates has the following convention
fix #123 Title of a bug fix commit feat #234 Title of a cool new feature
In this case using
kraken-release-notes -t "^([a-z]+) #(\d+) (.*)$" -m type -m issue -m title v1.3.6..HEAD html
generates the additional fields on the commit object
typefirst capturing block
issuesecond capturing block
titlethird capturing block (redefines the title)
kraken-release-notes -t "^(\w*)(?:\(([\w\$\.]*)\))?\: (.*)$" -m type -m scope -m title v1.1.2..v1.1.3 markdown
To execute from this source against another repository, use a command like
node index.js -p C:\Code\other-repo 0841c28..9a480d5 ./templates/html-bootstrap.ejs > other-repo-notes.html
If the output is not what you expect, set the
DEBUG environment variable:
DEBUG=release-notes:* kraken-release-notes ...
SET DEBUG=release-notes:* kraken-release-notes ...