build-changelog
v2.1.2
Published
A CLI to auto-generate a deploy ready changelog
Downloads
19
Readme
build-changelog
A CLI to auto-generate a deploy ready changelog
Table of Contents generated with DocToc
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