Generate a changelog from git metadata
- Used by AngularJS and related projects.
- Everything internally or externally is pluggable.
- High performant. It doesn't spawn any extra child process to fetch data.
- Intelligently setup defaults but you can still modify them to your needs.
- Fully configurable. There are several presets that you can use if you just want to use the same conventions. But it is also possible to configure if you want to go down to the nth degree.
- Task runner integrations: grunt/gulp.
- Actively maintained.
$ npm install conventional-changelog
Note: As 0.1.x this module is rewritten and so the API is not backward compatible. If you are still using 0.0.x please checkout the README in your downloaded package or dig through the old tags.
- https://github.com/ajoslin/conventional-changelog/blob/master/CHANGELOG.md
- https://github.com/karma-runner/karma/blob/master/CHANGELOG.md
- https://github.com/btford/grunt-conventional-changelog/blob/master/CHANGELOG.md
var conventionalChangelog = require('conventional-changelog');
conventionalChangelog({
preset: 'angular'
})
.pipe(process.stdout);
Returns a readable stream.
Type: string
Possible values: 'angular'
, 'jquery'
, 'jshint'
, 'eslint'
A set of options of a popular project so you don't have to define everything in options, context, gitRawCommitsOpts, parserOpts or writerOpts manually. The preset values can be overwritten.
Type: object
Type: string
Default: 'package.json'
The location of your "package.json".
Type: function
Default: pass through
A function that takes package.json
data as the argument and returns the modified data. Note this is performed before normalizing package.json data. Useful when you need to add a leading 'v' to your version or modify your repository url, etc.
Type: boolean
Default: false
Should the log be appended.
Type: boolean
Default: false
Set to true
if you want to generate all blocks of the log. false
if you just want to generate the current one.
Type: function
Default: function() {}
A warn function. EG: grunt.verbose.writeln
Type: object
Default: through.obj()
A transform stream that applies after the parser and before the writer.
See the conventional-changelog-writer docs. There are some defaults:
Default: normalized host found in package.json
.
Default: version found in package.json
.
Default: extracted from normalized package.json
repository.url
field.
Default: extracted from normalized package.json
repository.url
field.
See the git-raw-commits docs. There are some defaults:
Default: '%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'
Default: latest semver tag if options.allBlocks
is false
.
Default: only true
if options.append
is truthy.
See the conventional-commits-parser docs.
See the conventional-changelog-writer docs. There are some defaults:
Default: same as options.append
.
$ npm install -g conventional-changelog
$ conventional-changelog --help
Generate a changelog from git metadata
Usage
conventional-changelog
Example
conventional-changelog -i CHANGELOG.md --overwrite
Options
-i, --infile Read the CHANGELOG from this file
-o, --outfile Write the CHANGELOG to this file. If unspecified, it prints to stdout
-w, --overwrite Overwrite the infile
-p, --preset Name of the preset you want to use
-k, --pkg A filepath of where your package.json is located
-a, --append Should the generated block be appended
-b, --all-blocks Generate all blocks
-v, --verbose Verbose output
-c, --context A filepath of a javascript that is used to define template variables
--git-raw-commits-opts A filepath of a javascript that is used to define git-raw-commits options
--parser-opts A filepath of a javascript that is used to define conventional-commits-parser options
--writer-opts A filepath of a javascript that is used to define conventional-changelog-writer options
- conventional-github-releaser - Make a new GitHub release from git metadata
- conventional-recommended-bump - Get a recommended version bump based on conventional commits
This module has options append
and allBlocks
. However, it doesn't read your previous changelog. Reasons being:
- The old logs is just to be appended or prepended to the newly generated logs, which is a very simple thing that could be done in the parent module.
- We want it to be very flexible for the parent module. You could create a readable stream from the file or you could just read the file.
- We want the duty of this module to be very minimum.
So, when you build a parent module, you need to read the old logs and append or prepend to them based on options.append
. However, if options.allBlocks
is true
you need to ignore any previous logs.
- Make changes
- Commit those changes
- Make sure Travis turns green
- Bump version in
package.json
conventionalChangelog
- Commit
package.json
andCHANGELOG.md
files - Tag
- Push
The reason why you should commit and tag after conventionalChangelog
is that the CHANGELOG should be included in the new release, hence gitRawCommitsOpts.from
defaults to the latest semver tag.
MIT