Writing Clear Changelogs for Laravel Packages

Laravel package maintainers need to tell users what changed between releases and what to do before upgrading. A changelog is a dated, version-by-version record of notable changes, written for the people who install and use the package. Clear entries help users spot changes that would break their code before they upgrade.

Keep CHANGELOG.md at the package’s root. Put the newest information first and explain what each change means for package users. Separate breaking changes from fixes. When users need to change their code or configuration, give them specific upgrade steps.

Organize entries around user-visible changes

Group entries by release, then by the kind of change. The Keep a Changelog format uses an Unreleased section for changes planned for the next release, followed by released versions and their dates. It recommends categories for additions and changes (Added and Changed), deprecations (Deprecated), removals (Removed), fixes (Fixed), and security updates (Security). Use the date format YYYY-MM-DD so readers do not have to interpret regional date conventions.

Choose categories that help users find information quickly. “Fixed” should describe a defect and its effect. “Added” should identify a new feature or supported option. “Changed” should describe a behavior or interface change that remains compatible. A deprecation warns users that a feature is scheduled for removal; a removal records when it is gone.

Write each entry so a user can understand what changed without inspecting commits. For example, “Fixed the command returning an error when the configured queue is empty” tells a user more than “Fixed queue handling.” Commit messages and diffs help maintainers track development, but they include implementation details and other noise. Turn them into entries users can understand instead of copying them directly into the changelog.

A real Laravel package changelog, laravel-events, uses Breaking and Upgrade sections alongside Added, Changed, and Fixed. That format shows how a package can add sections when its users need more direct guidance than the standard categories provide.

Mark breaking changes where users will see them

A breaking change requires a user to alter code or configuration for the package to work after an upgrade. In a Laravel package, that includes changes such as renaming a public method, adding a required argument, changing a configuration key, removing a service container binding, or changing a command’s required options. A change can be breaking even when the package’s own tests pass, because those tests do not cover every way users depend on its public features.

Give breaking changes a clearly labeled section near the top of the release notes. State what changed, which users are affected, and what they need to change. For example: “The package renamed its public send method to dispatch. Update calls to send to use dispatch before upgrading.” Keep a related entry in the relevant category, such as Changed or Removed, if that helps users find it there too.

When a package follows Semantic Versioning, maintainers use a major version change for incompatible changes and a minor version change for backward-compatible additions. They use a patch version change for backward-compatible fixes. The version number helps users judge upgrade risk, while the changelog explains the actual impact. Packages in the 0.x series need extra care: the usual stability expectations do not apply in the same way, so describe incompatible changes explicitly rather than relying on the version number alone.

Make the upgrade path explicit

A breaking-change notice warns users that an upgrade requires action. An upgrade section tells them what to do. Include one when users need to update calls, revise configuration, rerun a package-specific setup step, or meet a new compatibility requirement. Put the steps in the order users should perform them, and identify the old and new names or behavior precisely.

For example, if a package removes a configuration key, say which key to remove or replace, what setting takes its place, and whether users must republish or edit their configuration file. If a new release changes a public method’s required arguments, show which calls need updating and explain the new requirement. Avoid instructions such as “update your configuration accordingly”; they leave users to guess what to inspect.

Deprecation notices give users time to prepare for removal. When a package marks a method or setting as deprecated, tell users what replaces it and that the package plans to remove it in a later release. In a later release, record the removal under Breaking or Removed and link it to the corresponding upgrade instructions. That connection helps users follow the change across releases.

Keep the changelog current

Add entries when changes affect package users, then review them before publishing each release. An empty or outdated Unreleased section can mislead users about what the next release contains. Release notes should match the code and the published version.

Use CHANGELOG.md as the durable record and link version headings or issue references when they help users find more detail. Release pages can repeat or summarize the notes, but relying on GitHub Releases alone makes the history less portable and harder to find outside that platform. If you withdraw a release, mark it as yanked and label it [YANKED] so users can see that it was withdrawn.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com