Node Auto-Changelog

node-autochglog is a CLI tool that generates a changelog based on commit messages, assuming that they're written using the Conventional Commits syntax. It is meant to be used in CI/CD pipelines, or in pre-commit hooks.

Data model

Here are some concepts to better understand the logic behind the tool:

• to the purpose of this tool, a Changelog is a list of Release items;
• each Release item may contain scopes, each of which contains a list of Category items; when no commit in the entire changelog has a scope, scope headings are omitted and categories sit directly under the release;
• each Category item contains a list of Commit items.

In other words, a changelog is a list of releases, each release contains a number of commits, that are arranged in categories (and optionally grouped by scope) within the release they belong to.

Releases are defined by git tags, categories are defined by Conventional Commit type prefixes, and scopes are defined by the optional Conventional Commit scope (e.g. feat(api): ...).

Installation

node-autochglog can be launched through npx, so no installation is required. If you still want to install it, this section explains how to do that.

For making it available within a project:

npm install save-dev node-autochglog

For making it available globally:

npm install -g node-autochglog

Usage

In order to use node-autochglog, just run the following command in the root of the project you want to generate a changelog for:

npx node-autochglog

Configuration

The tool accepts configuration from a node-autochglog.config.json, expected to be found in the directory where the node-autochglog command is executed; the file is expected to contain a single JSON object adhering to the NodeAutoChglogConfig interface:

export interface NodeAutoChglogConfig {
  tagFilter: string;
  initialTag: string;
  templateLocation: string;
  targetBranch: string;
  outputFilepath: string;
  allowedCategories: { key: string; label?: string }[];
  allowedScopes: { key: string; label?: string }[];
  stripPRNumbers: boolean;
  ignoreScope: boolean;
  unscopedLabel: string;
}

Complete configuration example

{
  "tagFilter": "^\\d+\\.\\d+\\.\\d+$",
  "initialTag": "Unreleased",
  "templateLocation": "",
  "targetBranch": "main",
  "outputFilepath": "CHANGELOG.md",
  "allowedCategories": [
    { "key": "feat", "label": "Features" },
    { "key": "fix", "label": "Fixes" },
    { "key": "refactor", "label": "Refactoring" },
    { "key": "ci", "label": "Integration" },
    { "key": "docs", "label": "Documentation" }
  ],
  "allowedScopes": [
    { "key": "api", "label": "API" },
    { "key": "ui", "label": "User Interface" },
    { "key": "arch", "label": "Architecture" },
    { "key": "auth", "label": "Authentication" }
  ],
  "stripPRNumbers": true,
  "ignoreScope": false,
  "unscopedLabel": "General"
}