Easy Test Changelog Automation

Automate changelog validation and testing by scanning commit history, verifying CHANGELOG format, and integrating checks into your CI pipeline.

When to Use This Command

Run this command when...

• You want to verify that every PR includes a properly formatted CHANGELOG entry
• You are setting up CI checks to enforce changelog discipline across your team
• You need to audit whether recent releases have complete changelog coverage

Avoid this command when...

• Your project uses a fully automated release-notes generator like semantic-release
• You are working on a solo project with no formal release process

Quick Start

Copy
# .claude/commands/easy-test-changelog-automation.md
---
allowed-tools: ["Bash", "Read", "Glob"]
---
Scan the repository for CHANGELOG files. Validate format against
Keep a Changelog spec. Check that recent commits have entries.

Example usage:

/easy-test-changelog-automation validate

Example output:

Found: CHANGELOG.md (Keep a Changelog format)
Validating structure...
  [PASS] ## [Unreleased] section exists
  [PASS] Entries grouped by Added/Changed/Fixed
  [WARN] 3 commits since last release lack entries
Summary: 2 passed, 0 failed, 1 warning

Core Concepts

Concept	Description
Format detection	Identifies Keep a Changelog, Conventional, or custom formats
Entry validation	Checks headings, date formats, and link references
Commit coverage	Cross-references git log against changelog entries
CI integration	Generates exit codes suitable for GitHub Actions or GitLab CI

git log --> extract commits --> match against CHANGELOG
                |                        |
                v                        v
        missing entries           format violations
                \                       /
                 +--- report + exit code

Configuration

Option	Default	Description
format	auto	Expected changelog format (keepachangelog, conventional)
since	last-tag	How far back to check commit coverage
strict	false	Treat warnings as errors
ignore-merge	true	Skip merge commits from coverage check
output	text	Report format (text, json, markdown)

Best Practices

1. Add to CI early -- the sooner you enforce changelog entries, the less catch-up work later.
2. Use the Unreleased section -- accumulate changes there and promote them to a version heading at release time.
3. Ignore merge commits -- they duplicate information and create false negatives in coverage checks.
4. Pair with conventional commits -- standardized commit messages make automated matching far more reliable.
5. Review warnings regularly -- a warning today becomes a missing entry in the release notes tomorrow.

Common Issues

1. "No CHANGELOG file found" -- The command looks for CHANGELOG.md, CHANGELOG, or changelog.md in the repo root. Create one or specify the path.
2. False coverage gaps -- Commits that touch only CI config or docs may not need changelog entries. Use an ignore pattern for non-user-facing paths.
3. Date format mismatch -- Keep a Changelog expects ISO 8601 dates (YYYY-MM-DD). Other formats will trigger a validation error.