build-changelog

build-changelog

A CLI to auto-generate a deploy ready changelog

Table of Contents generated with DocToc

• build-changelog
  • Usage
    • Steps of changelog procedure
  • Example
  • Example changelog file
    • Involved example
    • Parsing a changelog file
  • Docs
    • Type definitions
    • buildChangelog(options, cb<Error, String>)
      • options.folder
      • options.nextVersion
      • options.major
      • options.patch
      • options.logFlags
    • var changelog = parseChangelog(text)
      • text
  • Installation
  • Tests
  • Contributors

Usage

$ build-changelog [flags]

See usage.md for more documentation

Steps of changelog procedure

Running build-changelog will do the following steps.

• Bump the minor version number and update the package.json and npm-shrinkwrap.json.
• Generate the changelog additions. Generate a header line that conatins the date & version number and then find all the commits since the last build-changelog call. Add the header and commits to the CHANGELOG file
• Commit the package.json, shrinkwrap and CHANGELOG changes as a new version number and tags the commit as vVERSION_NUMBER

Example

var buildChangelog = require('build-changelog');

// takes any commits not written to the changelog and adds them
// reads package.json in process.cwd() to find the new version
// to set the project to.
buildChangelog(process.cwd(), function (err, nextVersion) {
    if (err) throw err;

    console.log('the new version', nextVersion);
});

Example changelog file

2014-03-04 - 1.1.0 (f6ec3cc)
f6ec3cc (HEAD, initial-version) better documentation
e207a6e allow a string opts
0a77206 (origin/initial-version) make npm run cover work
df03ac1 test with two calls
b8b0f0f refactor test
fa1b602 added a naive cli
bd78f26 added tests
d3df8cc initial code
ca5bda1 the individual tasks
e3b8fd4 docs
8b5d269 (origin/master, master) initial

Involved example

var updateVersion = require('build-changelog/tasks/update-version')
var updateChangelog = require('build-changelog/tasks/update-changelog')
var commitChanges = require('build-changelog/tasks/commit-changes')

var opts = {
    nextVersion: '1.1.0',
    logFlags: '--oneline --decorate --first-parent',
    folder: process.cwd()
};

// skip this step if you dont want to change the package.json
// version
updateVersion(opts, function (err) {
    if (err) throw err;

    updateChangelog(opts, function (err) {
        if (err) throw err;

        // skip this step if you dont want to commit or tag your
        // git repo
        commitChanges(opts, function (err) {
            if (err) throw err;

            console.log('done');
        });
    });
});

Parsing a changelog file

var path = require('path')
var readChangelog = require('build-changelog/changelog/read')

var loc = path.join(process.cwd(), 'CHANGELOG')

readChangelog(loc, function (err, changelog) {
    if (err) throw err;

    changelog.chunks.forEach(function (chunk) {
        console.log('header', chunk.header)
        console.log('commit lines', chunk.lines)
    })
})

Docs

Type definitions

See docs.mli for type definitions

buildChangelog(options, cb<Error, String>)

build-changelog := (folder: String | {
    folder: String,
    nextVersion?: String,
    major?: Boolean,
    minor?: Boolean,
    patch?: Boolean,
    filename?: String,
    logFlags?: String
}, cb: Callback<err: Error, nextVersion: String>)

Your cb will get called with an Error if any operation fails and will be called with a nextVersion string if the steps have completed successfully, the nextVersion string will be whatever version is written to the package.json file in the given folder

if options is a "string" then it's a shorthand for { folder: string }.

options.folder

This is the folder in which the CHANGELOG will be written to. It is assumed that the folder is also a git repository. The package.json and npm-shrinkwrap.json files there will also be edited.

options.nextVersion

When set to a valid semver string this version will be used to set the package.json version to. When not set a version number will be computed based on bumping either the minor, major or patch version.

options.major

This flag defaults to false. When set to true the major version number will be increased instead of the patch version number.

options.minor

This flag defaults to false. When set to true the minor version number will be increased instead of the patch version number.

options.patch

This flag defaults to true. When set to true the patch version number will be increased.

options.logFlags

To customize the generation of the actual CHANGELOG content you can pass extra flags to be passed to git log.

By default build-changelog runs git log --decorate --oneline. You may want to pass different flags, for example if you have a merge only git strategy you may want to pass --oneline --first-parent or if you have a squash only git strategy you may want to pass --oneline --no-merges.

options.filename

This defaults to CHANGELOG. You can specify a different filename to read and write the CHANGELOG to.

var changelog = parseChangelog(text)

type ChangeLogRecord := {
    chunks: Array<{
        header: {
            date: String,
            version: String,
            commit?: String
        },
        lines: Array<{
            sha?: String,
            decorations?: Array<String>,
            message: String 
        }>
    }>,
    content: String
}

build-changelog/changelog/record := 
    (content: String) => ChangeLogRecord

parseChangelog(text) will return a ChangeLog data record that is the structured form of the textual CHANGELOG file content.

the changelog returned contains an array of chunks, each chunk correspond to a versioned section of the changelog. A chunk contains a header section, for the versioned header line and an array of lines for each commit message.

text

A "string" of text, this will most likely be taken by reading your CHANGELOG file

Installation

npm install build-changelog

Tests

npm test

Contributors

• Raynos