Composer Changelogs Laravel Package

Getting Started

• Check your Composer binary first. 2.0.0 drops Composer 1 support entirely. Before upgrading the package, confirm every machine and CI image runs Composer 2 (composer --version). Docker images, Sail setups, and older CI templates are the usual offenders.
• Install as a dev dependency: composer require --dev vaimo/composer-changelogs. This is a build/release-time tool — never a runtime dependency, so composer install --no-dev deployments are unaffected.
• Allow the plugin. On Composer 2.2+ the plugin must be whitelisted in composer.json:

  "config": { "allow-plugins": { "vaimo/composer-changelogs": true } }
  

• Where to look first: the package README, then the extra.changelogs block in your root composer.json. Run composer list after install to see the commands the plugin registers, and check the bundled Mustache templates before writing your own.
• First use case: generate a CHANGELOG.md entry for a tagged release by grouping commits between the previous tag and HEAD into buckets (Features, Fixes, Breaking). Commit your existing history conventions first — the output quality is entirely a function of your commit subjects.

Implementation Patterns

• Release-time generation in CI. Run the generator on tag push, before creating the GitHub/GitLab release, and feed the output into the release body. Treat CHANGELOG.md as a build artifact that gets committed back, or generate it only into the release notes and keep the repo clean — pick one and be consistent.
• Configure buckets in extra.changelogs. Map commit prefixes or labels to section headings (feat: → Features, fix: → Fixes, !/BREAKING CHANGE → Breaking). Keep this config in the repo so every contributor produces identical output.
• Enforce commit conventions. Enable squash-merge with PR titles as commit subjects, or add a commitlint/PR-title check. The plugin can only classify what it can parse; sloppy merge commits produce empty or "Other" sections.
• Wire it into Composer scripts so it is discoverable: add a "changelogs" script alias (and optionally a post-update-cmd hook) so composer changelogs works locally without anyone memorising the binary path.
• Custom templates for Keep a Changelog. Copy the shipped .mustache template into your repo, adjust headings/ordering/link formats, and point the config at it. This is the main extension point — there is no Laravel service provider, no publishable config, and no container integration to lean on.
• Package repos over app repos. The tool earns its keep on libraries you tag and publish (internal Laravel packages, shared modules). On an application repo the value is narrower: drafting release notes between deploy tags or feeding a Slack "what shipped" message.

Gotchas and Tips

• Shallow clones break everything. GitHub Actions defaults to fetch-depth: 1, which gives the plugin no history and no tags. Set fetch-depth: 0 (or explicitly fetch tags) in your checkout step — this is the single most common CI failure.
• Version pinning during transition. If any environment still runs Composer 1, pin vaimo/composer-changelogs to the 1.x line until it is upgraded; 2.0.0 will simply refuse to install there.
• PHP floor moved down, not up. 7.1–7.3 are supported again, but this only matters for legacy projects — Laravel 8+ already requires 7.3+, and modern Laravel apps are on 8.2+. Don't read the change as a reason to downgrade anything.
• Symfony 8 support is forward-looking. The backwards-compatible range (Symfony 3/4 through 8) means the plugin keeps working across Laravel 8–12. Verify after upgrading that your symfony/* constraints did not shift unexpectedly in composer.lock.
• Mustache constraint was loosened. If your project also depends on mustache/mustache (or something that pulls it), a composer update can now bump it across a major version. Rendering differences in escaping, section handling, or {{.}} semantics can silently mangle your changelog — diff the generated output after the upgrade.
• Silent drops, not errors. Unparseable commit subjects are skipped, not flagged. If a release looks thin, run the command with -vvv and inspect the actual subject lines in the tag range (git log --oneline <prev>..HEAD).
• Tag hygiene matters. Missing, lightweight-vs-annotated, or out-of-order tags produce either an enormous diff range or an empty one. Confirm the "previous release" the plugin resolves is the one you expect.
• Keep it out of production images. Dev-only dependency; if you build a production image with composer install (no --no-dev), you are shipping a Composer plugin unnecessarily.