Automated changelog generator:package::zap::clipboard:
Absolutely customizable a release changelog with helpful plugins
yarn add changelog-gurunpm install changelog-guruChangelog-guru can be used either through a command line interface with an optional configuration file, or else through its JavaScript API. Run changelog --help to see the available options and parameters.
Create CHANGELOG.md:
changelog [options]
- allow generating
CHANGELOG.mdby script - allow ignoring commits
- provide better information when browsing the history
<type>(<scope>): <subject>
<markers>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The type of changes made by this commit, such as feat or fix.
Scope could be anything specifying place of the commit change.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on github as well as in various git tools.
Subject line contains succinct description of the change.
See the Marker plugin section for a more detailed description.
Control markers of the form !<name>, allow you to group, ignore or increase the priority of commits in the change log
All that allows you to write a conscience.
Changelog-guru uses cosmiconfig and you can configure the module in any way you like described in the documentation.
All options can be configured in the configuration file, this is where changelog-guru looks for configuration:
.changelogrcfile in JSON or YAML format.changelogrc.jsonfile.changelogrc.yaml,.changelogrc.yml, or.changelogrc.jsfilechangelogproperty inpackage.jsonchangelog.config.jsfile exporting a JS object
For example see .changelogrc.yaml. Also you can use changelog-guru with default configuration.
| Default | CLI Override | API Override |
|---|---|---|
github |
--provider <string> |
provider: <string> |
The type of service provider to receive information about the project. To set the type of service you want to use, you must:
- Set
provider: githuborprovider: gitlabin your configuration file, it's all. - Make sure the provider token is available as an environment variable.
Example:
export GITHUB_TOKEN="f941e0..."
export GITLAB_TOKEN="f941e0..."
Changelog-guru uses dotenv and you can loads environment variables from a
.env
| Default | CLI Override | API Override |
|---|---|---|
| see below | --major <items> |
major: string[] |
| see below | --minor <items> |
minor: string[] |
| see below | --patch <items> |
patch: string[] |
Default level of changes:
changes:
major:
- break
minor:
- feat
- improve
patch:
- fix
- chore
- refactor
- test
- docs
- build
- types
- style
- workflow
- perf
- revertFor a list of change types by level, see SemVer. The commits with the specified types will be distributed by change levels. For example:
// Commit message with MINOR changes
feat(Core): add awesome feature
The following types of changes are defined by default:
- MAJOR version:
break- breaking changes
- MINOR version:
feat- new featuresimprove- features improvements
- PATCH version:
fix- some bugs fixingchore- minor changesrefactor- code refactoringtest- add or change testsdocs- documentation changesbuild- package changes, releasetypes- code typingstyle-css/scss/other, style sheet changeworkflow- workflow changesperf- performance improvementsrevert- reverted changes
Parameters of the output file. Specify the path to the file and the excluded entities.
Default output options:
output:
filePath: CHANGELOG.md
exclude:
authorLogin: ['dependabot-preview[bot]']
commitType: ['build']
commitScope: ['deps', 'deps-dev']
commitSubject: ['merge']File path to write change log to it.
| Default | CLI Override | API Override |
|---|---|---|
CHANGELOG.md |
--output <path> |
filePath: string |
One way to filter output by ignoring commits with a given type, scope, subject, or from certain authors. To find out about other ways to ignore commits, see the section Plugins
| Default | CLI Override | API Override |
|---|---|---|
| see output example | --excl-authors<items> |
authorLogin: string[] |
| see output example | --excl-types <items> |
commitType: string[] |
| see output example | --excl-scopes <items> |
commitScope: string[] |
| see output example | --excl-subjects <items> |
commitSubject: string[] |
- authorLogin - excludes authors with the listed logins from the output file
- commitType - excludes commits with the listed types from the output file
- commitScope - excludes commits with the listed scopes from the output file
- commitSubject - excludes commits with the listed subjects from the output file
| Default | CLI | Description |
|---|---|---|
false |
--bump |
Based on data about changes made in the project, forms the next version number and bumps it in package.json, see SemVer |
| - | -v, --version |
Show changelog-guru package version |
| - | --help |
Show changelog-guru cli options help |
All plugin settings are described in the special section plugins of the configuration as follows:
plugins:
<plugin name>:
<plugins option>
...
<plugins option>Base plugin enabled by default. Displays information about changes to package.json in the change log. Checks the following sections:
Default options:
attention:
title: Important Changes
templates:
added: 'Added %name% with %val%'
changed: 'Changed %name% from %pval% to %val%'
bumped: 'Bumped %name% from %pver% to %ver%'
downgraded: 'Downgraded %name% from %pver% to %ver%'
removed: 'Removed %name%, with %pval%'
sections:
license: License
engines: Engines
dependencies: Dependencies
devDependencies: DevDependencies
peerDependencies: PeerDependencies
optionalDependencies: OptionalDependencies,Default: Important Changes
The name of the main section in which all other sections will be placed with changes by types.
The change message templates:
- added - added Dependencies
- changed - dependencies whose value is not
SemVerand has been changed - bumped - dependencies whose version was bumped
- downgraded - dependencies whose version was downgraded
- removed - removed dependencies
Literals available for substitution in Templates:
%name%- dependency name%ver%- semantic version of dependency, for example1.9.3%pver%- previous semantic version of dependency%val%- dependency version, for example^1.9.3%pval%- previous dependency version
Section names with dependency changes.
Base plugin enabled by default. Allows you to add additional useful information to the commit, for example, about breaking changes. Or allows you to hide the commit from the change log.
Two types of markers are available, action markers and join markers.
Default options:
marker:
actions:
- ignore
- group
joins:
important: Important Internal Changes
deprecated: DEPRECATIONS
break: BREAKING CHANGESAction markers performs operations on commits when building a change log:
!ignore- ignore a commit in output!group(<name>)- creates a group of commits with the<name>
Join markers combine commits in sections. Configured as follows:
<marker name>: <section title>
The following markers are available:
!important- place a commit title to special section on top of changelog!deprecated- place a commit title to special section with deprecated properties!break- indicates major changes breaking backward compatibility
Base plugin enabled by default. Renames areas and abbreviations to a more human-readable format.
Default options:
scope:
onlyPresented: false
names:
cr: Core
api: API
ssr: Server Side Rendering
fc: Functional Components
dts: TypeScript Declaration ImprovementsDefault: false
In the case of true will only rename the specified names.
List of abbreviations and their human-readable versions. Configured as follows:
<abbreviated name>: <human-readable name>
Base plugin enabled by default. Distributes commits with the specified types into sections. Configured as follows:
<section name>: [commit types]
Default options:
section:
Features: [feat]
Improvements: [improve]
Bug Fixes: [fix]
Internal changes: [types, workflow, build, test, chore, docs]
Performance Improvements: [perf]
Code Refactoring: [refactor]
Reverts: [revert]