$ npm install conventional-commits-template
Generate logs based on conventional commits and templates
Each input commit message consists of a hash (optional), a header, a body (optional) and a footer (optional).
<hash>
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header has a special format that includes a type, a scope (optional) and a subject
<type>(<scope>): <subject>
The footer should contain any information about Important Notes (optional) and is also the place to reference GitHub issues that this commit references (optional).
<important note>
<BLANK LINE>
<references>
$ npm install --save conventional-commits-template
var conventionalCommitsTemplate = require('conventional-commits-template');
conventionalCommitsTemplate(version, context, options);
It expects an object mode upstream and the object should look something like this:
{ hash: '9b1aff905b638aa274a5fc8f88662df446d374bd', header: 'feat(scope): broadcast $destroy event on scope destruction', type: 'feat', scope: 'scope', subject: 'broadcast $destroy event on scope destruction', body: null, footer: 'Closes #1', notes: [], references: [ { action: 'Closes', repository: null, issue: '1', raw: '#1' } ] } { hash: '13f31602f396bc269076ab4d389cfd8ca94b20ba', header: 'feat(ng-list): Allow custom separator', type: 'feat', scope: 'ng-list', subject: 'Allow custom separator', body: 'bla bla bla', footer: 'BREAKING CHANGE: some breaking change', notes: [ { title: 'BREAKING CHANGE', text: 'some breaking change' } ], references: [] }
Each chunk should be a commit. Json object is also valid.
Returns a transform stream.
Type: string
Version number of the up-coming release. This argument is mandatory.
Variables that will be interpolated to the template.
Type: string Default: ''
Type: boolean Default: semver.patch(version) === 0
By default, this value is true if version's patch is 0.
Type: string
The hosting website. Eg: 'https://github.com/' or 'https://bitbucket.org/'
Type: string
The repository name on host. Eg: 'stevemao/conventional-commits-template'.
Type: boolean Default: true if host, repository, commit and issue are truthy
Should all references be linked?
Type: string Default: 'commits'
Commit keyword in the url if options.linkReferences === true.
Type: string Default: 'issues'
Issue or pull request keyword in the url if options.linkReferences === true.
Type: string Default: dateFormat(new Date(), 'yyyy-mm-dd', true)
Default to formatted ('yyyy-mm-dd') today's date. dateformat is used for formatting the date.
Type: object
Type: string Default: 'type'
How to group the commits. If this value is falsy, commits are not grouped.
Type: number Default: 7
Instead of outputting the full SHA-1 values of the hash, try to abbreviate them to a shorter unique name.
Type: number Default: 80
The maximum subject length.
Type: object Default: type: { fix: 'Bug Fixes', feat: 'Features', perf: 'Performance Improvements' }
Replace with new values in each commit.
Type: object Default: { 'BREAKING CHANGE': 'BREAKING CHANGES' }
Replace with new group titles. If a note's title is not in this mapping, the note will be ignored.
Type: function, string or array Default: 'title'
A compare function used to sort commit groups. If it's a string or array, it sorts on the property(ies) by localeCompare.
The string can be a dot path to a nested object property.
Type: function, string or array Default: ['scope', 'subject']
A compare function used to sort commits. If it's a string or array, it sorts on the property(ies) by localeCompare.
The string can be a dot path to a nested object property.
Type : function Default: 'title'
A compare function used to sort note groups. If it's a string or array, it sorts on the property(ies) by localeCompare.
The string can be a dot path to a nested object property.
Type: function Default: sort by localeCompare.
A compare function used to sort note groups. If it's a string or array, it sorts on the property(ies) by localeCompare.
The string can be a dot path to a nested object property.
Type: string Default: template.hbs
The main handlebar template.
Type: string Default: header.hbs
Type: string Default: commit.hbs
Type: string Default: footer.hbs
Type: object
Partials that used in the main template, if any. The key should be the partial name and the value should be handlebar template strings. NOTE: This value will overwrite headerPartial, commitPartial and footerPartial. If you are using handlebar template files, read files by yourself.
It is possible to customize this the changelog to suit your needs. Templates are written in handlebar. You can customize all partials or the whole template. Template variables are from either upstream or context. The followings are a suggested way of defining variables.
Variables in upstream are commit specific and should be used per commit. Eg: commit date and commit username. You can think of them as "local" or "isolate" variables.
context should be module specific and can be used across the whole log. Thus these variables should not be related to any single commit and should be generic information of the module or all commits. Eg: repository url and author names, etc. You can think of them as "global" or "root" variables.
Basically you can make your own templates and define all your template variables. This module can iterate the commits and compile them. For more details, please checkout handlebar and the source code of this module.
$ npm install --global conventional-commits-template
$ conventional-commits-template --help
Usage
conventional-commits-template [<path>...]
Example
conventional-commits-template commits.ldjson -v 1.0.0
cat commits.ldjson | conventional-commits-template -v 1.0.0
Options
-v, --ver Version number of the up-coming release
-t, --context A filepath of a json that is used to define template variables
-o, --options A filepath of a javascript object that is used to define options
It works with Line Delimited JSON.
If you have commits.ldjson
{"hash":"9b1aff905b638aa274a5fc8f88662df446d374bd","header":"feat(ngMessages): provide support for dynamic message resolution","type":"feat","scope":"ngMessages","subject":"provide support for dynamic message resolution","body":"Prior to this fix it was impossible to apply a binding to a the ngMessage directive to represent the name of the error.","footer":"BREAKING CHANGE: The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.\nCloses #10036\nCloses #9338","notes":[{"title":"BREAKING CHANGE","text":"The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive."}],"references":[{"action":"Closes","repository":null,"issue":"10036","raw":"#10036"},{"action":"Closes","repository":null,"issue":"9338","raw":"#9338"}]}
And you run
$ conventional-commits-template commits.ldjson --ver 1.0.0
The results will be
<a name=1.0.0></a>
## 1.0.0 (2015-03-25)
### Features
* **ngMessages:** provide support for dynamic message resolution 9b1aff9, closes #10036 #9338
### BREAKING CHANGES
* The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.
It is printed to stdout.
MIT © Steve Mao