Changelog Updater Laravel Package

Getting Started

• Install as a dev dependency: composer require --dev claudiodekker/changelog-updater. It is a build/release-time tool, not a runtime dependency — never install it in require.
• The package ships a CLI binary; confirm the exact interface for your version with vendor/bin/changelog-updater --help before wiring it into scripts. Flag names have been stable in practice but are not covered by a BC promise in a 1.x release.
• As of v1.2.0 the tool supports PHP 8.4. The minimum is still 8.1-era, so no constraint bump is needed on older projects.
• First use case: point the updater at your CHANGELOG.md and a Markdown file of release notes, and let it merge the notes under a new version heading following Keep a Changelog conventions (## [1.2.0] - 2025-08-12 plus ### Added / ### Fixed subsections).
• Where to look first: your existing CHANGELOG.md structure (heading level, version prefix, date format) — the tool mirrors what is already there, so an inconsistent changelog is the usual source of surprises. Then read the release-notes input format, and finally the comparison-link footer if you use one.
• The simplest day-one loop: write release notes to release-notes.md, run the updater locally, inspect git diff CHANGELOG.md, commit. Get this working by hand before automating anything.

Implementation Patterns

• CI-driven release flow. In a GitHub Actions release job, capture the release body (gh release view "$TAG" --json body -q .body > release-notes.md), run the updater against the checked-out changelog, commit the result on the default branch, and only then publish the tag. Keep the changelog commit separate from code commits so history stays readable.
• Two-phase releases. Generate notes → update changelog → commit → tag. Trying to do all of it in one step makes rollbacks messy, because the changelog commit is the only thing you usually want to revert.
• Composer script wrapper. Add "changelog": "@php vendor/bin/changelog-updater ..." under scripts so contributors run composer changelog instead of memorising flags. Pair it with a changelog:check script that fails when the file is out of sync.
• Unreleased section handling. Decide once whether you accumulate entries under ## [Unreleased] and roll them into a version at release time, or write version sections directly at release time. Mixing both produces duplicate headings — which is exactly the shape of the bug fixed in 1.2.0.
• Idempotency check. Run the updater twice for the same version on a scratch branch and diff. A correct run should be a no-op the second time. Wrap this in a test or a CI smoke step; it catches heading-detection regressions cheaply.
• Laravel app integration. If the rest of your release tooling lives in Artisan commands, wrap the binary with Symfony\Component\Process\Process in a small ReleaseChangelogCommand rather than shelling out from PHPUnit or a service provider. Keep it out of request-path code entirely.
• Bot commit hygiene. When CI commits the changelog, use a dedicated bot identity and [skip ci] in the message to avoid recursive workflow runs.

Gotchas and Tips

• Upgrade to 1.2.0 before your next release. v1.1.0 had a data-loss bug with duplicate sections (issue #9, fixed in #10): if your changelog contains more than one ### Added/### Fixed heading in the same version block — common after merge-heavy release cycles — entries could be silently dropped. Because the loss is silent, audit existing changelogs against git history once after upgrading rather than assuming past runs were clean.
• Always run against a clean working tree. The tool rewrites the changelog in place. If you have uncommitted edits, a bad run mixes your changes with its output and git diff stops being a reliable review artefact.
• Version string mismatch is the #1 failure mode. v1.2.0 versus 1.2.0, or ## [1.2.0] versus ## 1.2.0, can produce a second heading instead of updating the existing one. Match the existing file exactly and assert on it in CI.
• Watch the diff for whitespace churn. Merging Markdown blocks frequently introduces or removes trailing blank lines and can flip CRLF/LF on Windows checkouts. Add .gitattributes (CHANGELOG.md text eol=lf) to keep diffs honest.
• Pin the version in CI. Use composer require --dev claudiodekker/changelog-updater:^1.2 and commit the lockfile. An unpinned release tool that rewrites a tracked file is a supply-chain and reproducibility hazard.
• Link footers. If your changelog ends with [1.2.0]: https://.../compare/... reference links, verify after each run that the new entry's link was added and the previous one updated — this is the part most likely to need a manual touch-up.
• PHP 8.4 in the matrix. Adding 8.4 to your CI matrix is safe for this release (additive support only, no deprecations or BC breaks noted in v1.2.0), but confirm your other dev tooling — PHPStan, PHPUnit, Pint — also runs on 8.4 before rolling it out broadly.
• Extension point. The tool's output is plain text, so custom behaviour (ordering section types, injecting a contributors block, enforcing a max line length) belongs in a small post-processing script you own, not in a fork. Forking a single-purpose release tool is a long-term maintenance cost.