Changelog Linter

Validate CHANGELOG.md files against the Keep a Changelog specification.

Commands

All commands use the bundled Python script at scripts/changelog_linter.py.

1. Lint a changelog

python3 scripts/changelog_linter.py lint <file> [--strict] [--format text|json|markdown]

Run all validation rules against a CHANGELOG.md file.

Flags:

• --strict — exit code 1 on any warning (not just errors)
• --format — output format: text (default), json, markdown

2. List versions

python3 scripts/changelog_linter.py versions <file> [--format text|json]

Extract and display all versions with dates and change counts.

3. Validate version ordering

python3 scripts/changelog_linter.py order <file> [--format text|json]

Check that versions are in descending semver order.

4. Check links

python3 scripts/changelog_linter.py links <file> [--format text|json]

Verify that all version headers have corresponding link references at the bottom.

Lint Rules (16 total)

Structure (5 rules)

1. missing-title — File doesn't start with # Changelog
2. missing-description — No description paragraph after title
3. no-versions — No version entries found
4. empty-version — Version section has no change entries
5. unreleased-missing — No [Unreleased] section

Versions (4 rules)

1. invalid-version — Version doesn't follow semver (MAJOR.MINOR.PATCH)
2. invalid-date — Date doesn't follow ISO 8601 (YYYY-MM-DD)
3. version-order — Versions not in descending order
4. duplicate-version — Same version appears twice

Sections (3 rules)

1. invalid-section — Section type not in spec (Added/Changed/Deprecated/Removed/Fixed/Security)
2. empty-section — Section header with no list items
3. section-order — Sections not in recommended order

Formatting (4 rules)

1. missing-link-ref — Version header has no corresponding link reference
2. broken-link-ref — Link reference exists but URL is empty or malformed
3. inconsistent-bullets — Mixed bullet styles (- and *)
4. trailing-whitespace — Lines with trailing whitespace

Output Formats

Text (default)

CHANGELOG.md:15 error [invalid-date] Version 1.2.0 has invalid date: "March 2024" (expected YYYY-MM-DD)
CHANGELOG.md:28 warning [empty-section] Section "Deprecated" under 1.1.0 has no entries
CHANGELOG.md:45 warning [missing-link-ref] Version 1.0.0 has no link reference

3 issues (1 error, 2 warnings)

JSON / Markdown

Standard structured output with issues, summary, and version list.

CI Integration

- name: Lint Changelog
  run: python3 scripts/changelog_linter.py lint CHANGELOG.md --strict

Exit codes: 0 = valid, 1 = issues found.