Keep A Changelog Laravel Package

Getting Started

Install via Composer: composer require --dev phly/keep-a-changelog. Run the CLI to initialize a changelog: vendor/bin/changelog init, which creates a valid CHANGELOG.md with the standard header and ## [Unreleased] section. The first practical use case is adding a new change while developing: vendor/bin/changelog add --type added --desc "New feature X" — this appends to the ## [Unreleased] section under the appropriate category header (e.g., ### Added). Entries are auto-formatted per Keep a Changelog conventions.

Implementation Patterns

• Pre-commit hook: Add a script to composer.json scripts (e.g., "changelog:add": "changelog add") and integrate via husky or Git hooks to validate or pre-format entries.
• CI enforcement: In GitHub Actions or similar, run changelog check to fail builds if CHANGELOG.md is out of sync or missing entries before a PR merge.
• Release workflow: After version tagging, run changelog release <version> --date="YYYY-MM-DD" — it promotes ## [Unreleased] content to a new versioned section and starts a fresh ## [Unreleased].
• Team collaboration: Use changelog list --type fixed to audit recent fixes before a release, or changelog show --version v1.2.3 to preview release notes for a tag.

Gotchas and Tips

• Markdown header consistency: The CLI expects ## [Unreleased] and ## [<version>] headers — avoid renaming or changing casing manually, or the tool may misplace entries. Use --type flags strictly (added, changed, fixed, removed, deprecated, security).
• Date format matters: Always use ISO 8601 (YYYY-MM-DD) with the --date flag during release; mismatches can cause invalid links or sorting issues.
• Partial edits cause drift: If you manually edit CHANGELOG.md, ensure no extra blank lines break category detection. The parser is fragile around indentation and spacing — use changelog validate to catch issues.
• Extension point: Use changelog add --custom-section "Security" for non-standard categories, but prefer using built-in types for interoperability.
• Git tagging alignment: Run release before tagging — if the version already exists in Git, links may point to non-existent tags. Confirm git describe --tags --abbrev=0 matches the release version.