`changelog-lint`

A simple linter for changelog files.

Installation

go install github.com/chavacava/changelog-lint@master

Usage

changelog-lint

will lint the CHANGELOG.md file in the current directory

changelog-lint some/path/changes.md

will lint the changes.md file in the some/path directory

To get the full list of command line flags:

$ changelog-lint -h
Usage of changelog-lint:
  -config string
        set linter configuration
  -release string
        enables release-related checks (the given string must be the release version, e.g. 1.2.3)
  -version
        get changelog-lint version

Configuration

If defaults do not fit your needs you can configure the linter by providing a configuration file with the command line flag -config

Via the configuration file you can:

Disable rules (all enabled by default)
Provide arguments to rules
Overwrite default parser patterns

The format of the configuration file is TOML. Example, the configuration to lint the CHANGELOG.md of nodejs/changelog-maker could be:

[parser.patterns]
    title=".*"
    version='^## \[(\d+\.\d+\.\d+)\]\(https:\/\/github\.com\/nodejs\/changelog-maker\/compare\/v\d+\.\d+\.\d+\.\.\.v\d+\.\d+\.\d+\) \(\d{4}-\d{2}-\d{2}\)$'
    subsection= '^### (?:⚠ )?([A-Z]+.*)$'

[rule.subsection-order]
    Disabled=true
[rule.subsection-naming]
    Arguments=["BREAKING CHANGES", "Features", "Bug Fixes", "Trivial Changes"]

Please notice some patterns require to have a capturing group (see Details below)

Error codes

Executing the linter returns one of the following error codes

Code	Meaning
`0`	no error
`1`	bad execution parameters/flags (e.g. bad changelog filename)
`2`	syntax error in the changelog file
`3`	the linter found a problem in the changelog

Details

The linter will apply a set of predefined rules (se below).

The expected global format of the file is Markdown where:

# is used for the main title,
## is used as header for versions,
### is used as header for subsections of versions,
* or - is used as item markers for change details entries

By default the following patterns are expected

Section	Pattern	Capturing Group
title	`^# .+$`	N/A
version	`^## (\d+\.\d+.\d+\\|\[Unreleased\])( .)$`	version name
subsection	`^### ([A-Z]+[a-z]+)[ ]*$`	subsection name
entry	`^[*-] .+$`	N/A

These patterns can be configured (see Configuration)

Check this CHANGELOG.md as example of the expected format.

Rules

Name	Description	Arguments
`subsection-empty`	warns on subsections without any entry
`subsection-namming`	warns on unknown subsection names (`Added`, `Changed`, `Deprecated`, `Fixed`, `Removed`, `Security` are known)	list of accepted section names (replaces the default list)
`subsection-order`	warns on subsections not listed alphabetically in a version
`subsection-repetition`	warns on subsections appearing more than once under the same version
`version-empty`	warns on versions without any subsection
`version-order`	warns on versions not well ordered wrt their semver number
`version-retpetition`	warns on versions appearing more than once

You can contribute new rules by implementing the linting.Rule interface:

type Rule interface {
    Apply(model.Changelog, chan Failure, RuleArgs)
    Name() string
}

chavacava / changelog-lint

readme