- name
- changelog-linter
- description
- Validate CHANGELOG.md files against the Keep a Changelog format (keepachangelog.com). Checks version ordering, date formats, section types, link references, and formatting. Use when asked to lint, validate, check, or audit a CHANGELOG.md file, verify changelog format, or ensure changelog follows Keep a Changelog conventions. Triggers on "lint changelog", "validate changelog", "check CHANGELOG.md", "changelog format".
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)
- missing-title — File doesn't start with
# Changelog - missing-description — No description paragraph after title
- no-versions — No version entries found
- empty-version — Version section has no change entries
- unreleased-missing — No
[Unreleased]section
Versions (4 rules)
- invalid-version — Version doesn't follow semver (MAJOR.MINOR.PATCH)
- invalid-date — Date doesn't follow ISO 8601 (YYYY-MM-DD)
- version-order — Versions not in descending order
- duplicate-version — Same version appears twice
Sections (3 rules)
- invalid-section — Section type not in spec (Added/Changed/Deprecated/Removed/Fixed/Security)
- empty-section — Section header with no list items
- section-order — Sections not in recommended order
Formatting (4 rules)
- missing-link-ref — Version header has no corresponding link reference
- broken-link-ref — Link reference exists but URL is empty or malformed
- inconsistent-bullets — Mixed bullet styles (
-and*) - 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 --strictExit codes: 0 = valid, 1 = issues found.