conventional-changelog-writer
Advanced tools
Write logs based on conventional commits and templates.
The conventional-changelog-writer npm package is a utility for generating changelogs based on commit messages that follow the Conventional Commits specification. It formats a changelog stream from parsed commit objects and allows customization of the output format.
Generate changelog
This code demonstrates how to use conventional-changelog-writer to generate a changelog from an array of commit objects. Each commit is written to the changelog stream, which formats them according to the specified context and options.
const writer = require('conventional-changelog-writer');
const commits = [
{hash: '123', type: 'feat', subject: 'add new feature'},
{hash: '456', type: 'fix', subject: 'fix bug'}
];
const context = {version: '1.0.0'};
const options = {};
const changelogStream = writer(context, options);
commits.forEach(commit => changelogStream.write(commit));
changelogStream.end();standard-version is a utility for versioning using semver and CHANGELOG generation powered by Conventional Commits. It automates version bumping and changelog generation, similar to conventional-changelog-writer, but also handles the creation of Git tags and commits.
lerna-changelog generates changelogs for monorepos managed by Lerna, based on pull requests and their labels. While it also focuses on changelog generation, it is specifically tailored for projects using Lerna and integrates with GitHub to enhance the changelog entries with PR links and author mentions.
Write logs based on conventional commits and templates.
# pnpm
pnpm add conventional-changelog-writer
# yarn
yarn add conventional-changelog-writer
# npm
npm i conventional-changelog-writer
import {
writeChangelogString,
writeChangelog,
writeChangelogStream
} from 'conventional-changelog-writer'
import { pipeline } from 'stream/promises'
// to write changelog from commits to string:
console.log(await writeChangelogString(commits, context, options))
// to write changelog from commits to async iterable:
await pipeline(
commits,
writeChangelog(context, options),
async function* (changelog) {
for await (const chunk of changelog) {
console.log(chunk)
}
}
)
// to write changelog from commits to stream:
commitsStream
.pipe(writeChangelogStream(context, options))
.pipe(process.stdout)
Commits it an async iterable of commit objects that looks 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', owner: null, 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: [] }
Parts of the commits will be formatted and combined into a log based on the handlebars context, templates and options.
The output log might look something like this:
## 0.0.1 "this is a title" (2015-05-29)
### Features
* **ng-list:** Allow custom separator ([13f3160](https://github.com/a/b/commits/13f3160))
* **scope:** broadcast $destroy event on scope destruction ([9b1aff9](https://github.com/a/b/commits/9b1aff9)), closes [#1](https://github.com/a/b/issues/1)
### BREAKING CHANGES
* some breaking change
Creates an async generator function to generate changelog entries from commits.
If includeDetails is true, instead of emitting strings of changelog, it emits objects containing the details the block.
Creates a transform stream which takes commits and outputs changelog entries.
If includeDetails is true, instead of emitting strings of changelog, it emits objects containing the details the block.
Create a changelog from commits.
Variables that will be interpolated to the template. This object contains, but not limits to the following fields.
Type: string
Version number of the up-coming release. If version is found in the last commit before generating logs, it will be overwritten.
Type: string
Type: boolean Default: semver.patch(context.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 owner of the repository. Eg: 'stevemao'.
Type: string
The repository name on host. Eg: 'conventional-changelog-writer'.
Type: string
The whole repository url. Eg: 'https://github.com/conventional-changelog/conventional-changelog-writer'.
Should be used as a fallback when context.repository doesn't exist.
Type: boolean Default: true if (context.repository or context.repoUrl), context.commit and context.issue are truthy
Should all references be linked?
Type: string Default: 'commits'
Commit keyword in the url if context.linkReferences === true.
Type: string Default: 'issues'
Issue or pull request keyword in the url if context.linkReferences === true.
Type: string Default: formatted ('yyyy-mm-dd') today's date in timezone set by timeZone option.
If version is found in the last commit, committerDate will overwrite this.
Writer options.
Type: function Default: defaultCommitTransform exported function.
A function to transform commits. Should return diff object which will be merged with the original commit.
Type: string Default: 'type'
How to group the commits. EG: based on the same type. If this value is falsy, commits are not grouped.
Type: function, string or array
A compare function used to sort commit groups. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.
Type: function, string or array Default: 'header'
A compare function used to sort commits. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.
Type: function, string or array 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. Will not sort if this is a falsy value.
Type: function, string or array Default: 'text'
A compare function used to sort note groups. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.
Type: function, string or null Default: if commit.version is a valid semver.
When the upstream finishes pouring the commits it will generate a block of logs if doFlush is true. However, you can generate more than one block based on this criteria (usually a version) even if there are still commits from the upstream.
If this value is a string, it checks the existence of the field. Set to null to disable it.
NOTE: It checks on the transformed commit chunk instead of the original one (you can check on the original by access the raw object on the commit). However, if the transformed commit is ignored it falls back to the original commit.
Type: function Default: pass through
Last chance to modify your context before generating a changelog.
Type: function Default: () => {}
A function to get debug information.
Type: boolean Default: false
The normal order means reverse chronological order. reverse order means chronological order. Are the commits from upstream in the reverse order? You should only worry about this when generating more than one blocks of logs based on generateOn. If you find the last commit is in the wrong block inverse this value.
Type: boolean Default: true
If true, reverted commits will be ignored.
Type: boolean Default: true
If true, the stream will flush out the last bit of commits (could be empty) to changelog.
Type: string Default: template.hbs
The main handlebars 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 handlebars template strings. If you are using handlebars template files, read files by yourself.
Type: string Default: 'UTC'
The timezone to use. The date in the changelog is generated based on timezone.
It is possible to customize this the changelog to suit your needs. Templates are written in handlebars. You can customize all partials or the whole template. Template variables are from either upstream or context. The following 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. A "raw" commit message (original commit poured from upstream) is attached to commit. transform can be used to modify a commit.
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 context. Extra context are based on commits from upstream and options. For more details, please checkout handlebars and the source code of this module. finalizeContext can be used at last to modify context before generating a changelog.
$ conventional-changelog-writer --help # for more details
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","owner",null,"repository":null,"issue":"10036","raw":"#10036"},{"action":"Closes","owner":null,"repository":null,"issue":"9338","raw":"#9338"}]}
And you run
$ conventional-changelog-writer commits.ldjson -o options.js
The output might look something like this
# 1.0.0 (2015-04-09)
### 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
FAQs
Write logs based on conventional commits and templates.
The npm package conventional-changelog-writer receives a total of 3,266,148 weekly downloads. As such, conventional-changelog-writer popularity was classified as popular.
We found that conventional-changelog-writer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.