Maintainer Laravel Package

Getting Started

• Install the package with Composer and publish its config (php artisan vendor:publish), then set the credentials for your AI provider (typically an API key plus a default model in config/ai.php and the package config). Verify the exact key names in the published config file — the release notes confirm no public config keys changed in 1.5.2.
• Look first at three places: the release changelog generator (LaravelAiReleaseChangelogGenerator, where validation and self::TYPES live), the agent (ReleaseChangelogAgent, which carries #[Strict] and #[UseCheapestModel]), and the package config for the commit range/tag source.
• First use case: generate changelog entries for the commits between two tags, e.g. run the package's changelog command (or call the generator from a test/command) against a small, already-tagged range. Start with a handful of commits so you can eyeball every generated type, scope, and description before wiring it into a real release.
• Sanity-check your commit history first: the generator works off Conventional Commits, and 1.5.2 makes that a hard requirement rather than a soft one.

Implementation Patterns

• CI release job. Invoke changelog generation as the first step of your release pipeline (on tag push or on the release branch, before tagging). Treat a non-zero exit as a blocked release — that is now the intended behaviour when AI output is non-conformant.
• Dry-run then commit. Generate into a temp file or stdout, review the diff, then write CHANGELOG.md and commit. This costs one extra step and saves you from a release that fails after the tag exists.
• Catch the generator's RuntimeException explicitly. The message carries the commit hash, a truncated debug representation of the bad type, and the full allowed set. Pipe it straight into your CI log/Slack notification; it is designed to be actionable without further triage.
• Use the agent directly for adjacent work. Because ReleaseChangelogAgent runs with #[Strict] and #[UseCheapestModel], it is a cheap, schema-validated structured-output agent. You can reuse it (or a subclass) to draft PR descriptions, release notes for a minor branch, or a "what changed" summary — anything that should be constrained to Conventional Commit types.
• Keep the human loop on type, not on prose. Structured output guarantees the enum, not the judgement. Reviewing whether a refactor was really a perf is the highest-value edit you can make; rewording descriptions is lower value.
• Swap the generator via the container if you need custom behaviour (e.g. different entry formatting or an extra validation pass). Bind your own implementation rather than editing vendor code — note that the allowed type set is exposed as a class constant, so changing which types are legal means extending the generator, not editing config.
• Write a test around your own commit range. A feature test that feeds a fixture commit list through the generator and asserts the resulting entry shape catches prompt/model drift before it blocks a release.

Gotchas and Tips

• This release is intentionally fail-fast. If a provider previously returned something like feature, bugfix, or a free-text category, your release now aborts. Audit any workflow, custom prompt, or fine-tuned model that was producing non-standard types before you upgrade — that is the only realistic migration work.
• Strict structured output is provider-sensitive. The request now asks for a strict JSON schema (strict: true) constraining entries[].type to feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Providers that do not fully honour strict JSON-schema mode may reject the request or silently degrade, so validate on your actual provider and model rather than assuming parity with OpenAI.
• null and non-string types are now hard failures, not coerced values. If you parse or post-process generator output yourself, do not rely on lenient handling downstream — it will never see those cases again.
• #[UseCheapestModel] plus #[Strict] is a deliberate trade. Cheap models with schema enforcement are fine for classification, but expect occasional retries or aborts on ambiguous commits. If you see repeated failures, improve the commit subject lines before upgrading the model — garbage-in still dominates here.
• Watch for the "truncated representation" in error messages. Long or whitespace-padded invalid values are shortened for readability; log the raw provider response separately if you need to debug a stubborn case.
• Changelog output is non-deterministic across runs. Do not regenerate on every build, and do not assert exact prose in tests — assert structure and the type enum only.
• Conventional Commits hygiene is now load-bearing. Squash-merge subjects like Fix stuff or WIP will either be skipped or produce a chore/revert-ish guess you will have to correct. Add a commit-lint check to the PR pipeline; it is cheaper than debugging a failed release at 6pm on a Friday.