Gathering detailed insights and metrics for conventional-changelog-writer
Generate changelogs and release notes from a project's commit messages and metadata.
Installations
npm install conventional-changelog-writerDeveloper Guide
BETA
Typescript
No
Module System
ESM
Min. Node Version
>=18
Node Version
18.20.2
NPM Version
10.5.0
Score
96
Supply Chain
99.5
Quality
82.5
Maintenance
100
Vulnerability
99.6
License
Releases
147
git-client: v1.0.1
git-client-v1.0.1
Updated on May 06, 2024
conventional-changelog: v6.0.0
conventional-changelog-v6.0.0
Updated on May 03, 2024
conventional-changelog-core: v8.0.0
conventional-changelog-core-v8.0.0
Updated on May 03, 2024
conventional-changelog-conventionalcommits: v8.0.0
conventional-changelog-conventionalcommits-v8.0.0
Updated on May 03, 2024
git-semver-tags: v8.0.0
git-semver-tags-v8.0.0
Updated on May 03, 2024
conventional-changelog-preset-loader: v5.0.0
conventional-changelog-preset-loader-v5.0.0
Updated on May 03, 2024
Contributors
148
Languages
3
TypeScript
JavaScript
Handlebars
TypeScript (56.7%)
JavaScript (40.52%)
Handlebars (2.78%)
Love this project? Help keep it running — sponsor us today! 🚀
Developer
conventional-changelog
Download Statistics
Total Downloads
740,424,459
Last Day
722,157
Last Week
4,513,509
Last Month
18,323,009
Last Year
194,139,085
GitHub Statistics
ISC License
7,979 Stars
1,722 Commits
724 Forks
56 Watchers
29 Branches
148 Contributors
Updated on Feb 15, 2025
Maintainers
4
Package Meta Information
Latest Version
8.0.0
Package Id
conventional-changelog-writer@8.0.0
Unpacked Size
87.13 kB
Size
22.66 kB
File Count
49
NPM Version
10.5.0
Node Version
18.20.2
Published on
May 03, 2024
Total Downloads
Cumulative downloads
Total Downloads
740,424,459
Last Day
2%
722,157
Compared to previous day
Last Week
5.7%
4,513,509
Compared to previous week
Last Month
35.3%
18,323,009
Compared to previous month
Last Year
25.2%
194,139,085
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
conventional-changelog-writer
Write logs based on conventional commits and templates.
Install • Usage • API • Customization • CLI
Install
1# pnpm 2pnpm add conventional-changelog-writer 3# yarn 4yarn add conventional-changelog-writer 5# npm 6npm i conventional-changelog-writer
Usage
1import { 2 writeChangelogString, 3 writeChangelog, 4 writeChangelogStream 5} from 'conventional-changelog-writer' 6import { pipeline } from 'stream/promises' 7 8// to write changelog from commits to string: 9console.log(await writeChangelogString(commits, context, options)) 10 11// to write changelog from commits to async iterable: 12await pipeline( 13 commits, 14 writeChangelog(context, options), 15 async function* (changelog) { 16 for await (const chunk of changelog) { 17 console.log(chunk) 18 } 19 } 20) 21 22// to write changelog from commits to stream: 23commitsStream 24 .pipe(writeChangelogStream(context, options)) 25 .pipe(process.stdout)
Commits it an async iterable of commit objects that looks like this:
1{ hash: '9b1aff905b638aa274a5fc8f88662df446d374bd', 2 header: 'feat(scope): broadcast $destroy event on scope destruction', 3 type: 'feat', 4 scope: 'scope', 5 subject: 'broadcast $destroy event on scope destruction', 6 body: null, 7 footer: 'Closes #1', 8 notes: [], 9 references: [ { action: 'Closes', owner: null, repository: null, issue: '1', raw: '#1' } ] } 10{ hash: '13f31602f396bc269076ab4d389cfd8ca94b20ba', 11 header: 'feat(ng-list): Allow custom separator', 12 type: 'feat', 13 scope: 'ng-list', 14 subject: 'Allow custom separator', 15 body: 'bla bla bla', 16 footer: 'BREAKING CHANGE: some breaking change', 17 notes: [ { title: 'BREAKING CHANGE', text: 'some breaking change' } ], 18 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:
1## 0.0.1 "this is a title" (2015-05-29) 2 3 4### Features 5 6* **ng-list:** Allow custom separator ([13f3160](https://github.com/a/b/commits/13f3160)) 7* **scope:** broadcast $destroy event on scope destruction ([9b1aff9](https://github.com/a/b/commits/9b1aff9)), closes [#1](https://github.com/a/b/issues/1) 8 9 10### BREAKING CHANGES 11 12* some breaking change
API
writeChangelog(context?: Context, options?: Options, includeDetails?: boolean)
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.
writeChangelogStream(context?: Context, options?: Options, includeDetails?: boolean): Transform
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.
writeChangelogString(commits: Iterable | AsyncIterable, context?: Context, options?: Options): Promise
Create a changelog from commits.
context
Variables that will be interpolated to the template. This object contains, but not limits to the following fields.
version
Type: string
Version number of the up-coming release. If version is found in the last commit before generating logs, it will be overwritten.
title
Type: string
isPatch
Type: boolean Default: semver.patch(context.version) !== 0
By default, this value is true if version's patch is 0.
host
Type: string
The hosting website. Eg: 'https://github.com' or 'https://bitbucket.org'
owner
Type: string
The owner of the repository. Eg: 'stevemao'.
repository
Type: string
The repository name on host. Eg: 'conventional-changelog-writer'.
repoUrl
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.
linkReferences
Type: boolean Default: true if (context.repository or context.repoUrl), context.commit and context.issue are truthy
Should all references be linked?
commit
Type: string Default: 'commits'
Commit keyword in the url if context.linkReferences === true.
issue
Type: string Default: 'issues'
Issue or pull request keyword in the url if context.linkReferences === true.
date
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.
options
Writer options.
transform
Type: function Default: defaultCommitTransform exported function.
A function to transform commits. Should return diff object which will be merged with the original commit.
groupBy
Type: string Default: 'type'
How to group the commits. EG: based on the same type. If this value is falsy, commits are not grouped.
commitGroupsSort
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.
commitsSort
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.
noteGroupsSort
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.
notesSort
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.
generateOn
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.
generateOn(keyCommit: Commit, commitsGroup: Commit[], context: FinalContext, options: FinalOptions): boolean
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.
finalizeContext(context: FinalContext, options: FinalOptions, filteredCommits: Commit[], keyCommit: Commit | null, commits: Commit[]): FinalContext | Promise
Type: function Default: pass through
Last chance to modify your context before generating a changelog.
debug
Type: function Default: () => {}
A function to get debug information.
reverse
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.
ignoreReverted
Type: boolean Default: true
If true, reverted commits will be ignored.
doFlush
Type: boolean Default: true
If true, the stream will flush out the last bit of commits (could be empty) to changelog.
mainTemplate
Type: string Default: template.hbs
The main handlebars template.
headerPartial
Type: string Default: header.hbs
commitPartial
Type: string Default: commit.hbs
footerPartial
Type: string Default: footer.hbs
partials
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.
timeZone
Type: string Default: 'UTC'
The timezone to use. The date in the changelog is generated based on timezone.
Customization Guide
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.
upstream
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
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.
CLI
1$ conventional-changelog-writer --help # for more details
It works with Line Delimited JSON.
If you have commits.ldjson
1{"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
1$ conventional-changelog-writer commits.ldjson -o options.js
The output might look something like this
1# 1.0.0 (2015-04-09) 2 3 4### Features 5 6* **ngMessages:** provide support for dynamic message resolution 9b1aff9, closes #10036 #9338 7 8 9### BREAKING CHANGES 10 11* 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.
License
MIT © Steve Mao
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
26 commit(s) and 2 issue activity found in the last 90 days -- score normalized to 10
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE.md:0
- Info: FSF or OSI recognized license: ISC License: LICENSE.md:0
Reason
Found 9/13 approved changesets -- score normalized to 6
Reason
6 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-67mh-4wv8-2f99
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/checks.yml:1
- Warn: no topLevel permission defined: .github/workflows/commit.yml:1
- Warn: no topLevel permission defined: .github/workflows/publish-all.yaml:1
- Warn: topLevel 'contents' permission set to 'write': .github/workflows/release-submodules.yaml:3
- Warn: no topLevel permission defined: .github/workflows/tests.yaml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/checks.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/checks.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/checks.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/checks.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/checks.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/checks.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/checks.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/checks.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/checks.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/checks.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/commit.yml:10: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/commit.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/commit.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/commit.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/commit.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/commit.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-all.yaml:7: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/publish-all.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish-all.yaml:8: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/publish-all.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-all.yaml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/publish-all.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:57: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:59: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:62: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/release-submodules.yaml:85: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/release-submodules.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:57: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:59: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:74: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:85: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:87: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:91: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:102: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:113: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/tests.yaml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tests.yaml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/conventional-changelog/conventional-changelog/tests.yaml/master?enable=pin
- Info: 0 out of 19 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 14 third-party GitHubAction dependencies pinned
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 27 are checked with a SAST tool
Score
4.8
/10
Last Scanned on 2025-02-10
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More