Building a Repeatable Laravel Package Release Process

Laravel package maintainers publish code that other developers install through Composer. A repeatable release process connects the code, its version, its documentation, and the package record users install. The key reference is a Git tag: a named pointer to a specific commit. Composer and Packagist use tags to identify released package versions.

For each release, maintainers assess compatibility, update the changelog and documentation, and run checks. They then tag the reviewed commit, publish release notes, and verify that consumers can install the version. These steps help prevent mismatched version numbers, incomplete release notes, and tags that point to the wrong code.

Choose a version from the compatibility impact

Semantic Versioning, or SemVer, uses three numbers in MAJOR.MINOR.PATCH order. Maintainers increment the patch number for backward-compatible fixes, the minor number for backward-compatible features and deprecations, and the major number for changes that break the public API. The SemVer specification defines those rules.

For a Laravel package, the public API includes more than PHP classes and methods. It can include configuration keys, service-provider behavior, Artisan commands, routes, views, migrations, and other integration points the package exposes. Laravel’s package development documentation describes these package resources and the role of service providers.

Choose the version based on how the change affects package users. If an existing application must change its code or package configuration to keep working, treat the change as a compatibility break when choosing the version. Passing tests does not settle the SemVer decision. Tests check the behavior covered by the suite; the maintainer must also judge compatibility with the published API.

Packages before 1.0.0 are in initial development under SemVer, and consumers should not assume their public APIs are stable. State the compatibility expectations for a 0.x package clearly.

When Composer reads a package from a version-control repository, it normally takes the released version from the tag. A tag such as v1.4.2 identifies a particular release; a consumer constraint such as ^1.4 tells Composer which versions it may select. Composer accepts the v prefix when interpreting tags, so choose one tag style and use it consistently. Avoid a hardcoded version field in composer.json for a VCS package, because it can conflict with the version Composer reads from tags. See Composer’s version guidance and library guidance.

Update the changelog and package documentation

Keep a CHANGELOG.md with an Unreleased section as changes accumulate. Before a release, move the relevant entries into a dated section for the new version, then create a fresh Unreleased heading. Keep a Changelog recommends reverse-chronological releases and clear categories such as Added, Changed, Deprecated, Removed, Fixed, and Security.

Write entries for package users rather than copying commit subjects. Explain what changed and what a user needs to do. Mark breaking changes clearly and include upgrade steps when a change requires them. Release notes can draw from the changelog, but maintainers should review generated notes for accuracy and relevance before publishing.

Check the README and other user-facing documentation against the release code. Confirm that installation and configuration instructions still work, and check that package-discovery instructions match the current composer.json metadata. If the package exposes commands, routes, views, migrations, or publishable resources, verify that the documentation describes their current behavior. Explain deprecations and breaking changes where users will find the relevant instructions.

Run checks before creating the tag

Run the package’s tests and configured quality checks before tagging. Laravel’s package-development documentation describes testing with a Workbench application in the official package skeleton and identifies Orchestra Testbench as an option for testing package code in a Laravel-like environment. Run integration tests that exercise the package inside Laravel. Also run static analysis and formatting checks if they are configured.

Run composer validate before committing the release state and before tagging. Composer says the command checks package metadata and, when a lock file exists, whether it is up to date with composer.json. Resolve relevant errors and warnings before proceeding; the Composer CLI documentation describes the command.

Check compatibility against the PHP and Laravel versions the package claims to support. The package’s declared support range determines which PHP and Laravel versions CI must cover, so maintainers should define that test matrix. Composer also recommends testing libraries against unlocked dependencies, including dependency updates and the lowest supported dependencies. Keep those checks in CI rather than using dependency updates as a release step, as Composer’s library guidance explains.

Before tagging, review the changelog and documentation alongside the code. Confirm the intended release commit and make sure the working tree has no unintended changes. Tag the commit that passed the release checks.

Tag the release-ready commit and publish its notes

Create the version tag only after the release-ready commit is settled, then push that tag to the repository. For example, a project using the v prefix could run:

git tag v1.4.2
git push origin v1.4.2

The example version is illustrative; use the version chosen from the compatibility review. Confirm that the remote tag points to the intended commit before creating the hosted release.

GitHub’s gh release create command creates a tag automatically if one does not exist. To prevent it from creating an unintended tag from the default branch, use the --verify-tag option when creating a GitHub release. Prepare the release notes from the matching changelog entry. Then confirm the release title and tag use the same version shown in those notes. The GitHub CLI documentation describes these options.

Treat a published version as permanent. SemVer says released contents must not be changed. Packagist announced on July 7, 2026, that stable version metadata on Packagist.org is immutable, so a corrected release should use a new version rather than moving an existing tag to different code. See Packagist’s announcement.

Verify Packagist and installation after publishing

After publishing, confirm that the remote tag still points to the intended commit and that Packagist lists the expected version and source. Then test dependency resolution from a clean consumer project using the released version. This checks the package as users receive it, rather than only checking the maintainer’s working copy.

If Packagist does not show the version immediately, check whether the repository’s update hook is configured. Allow time for synchronization or indexing before concluding that the tag is wrong. Packagist says it updates packages with hooks when they are pushed and crawls packages without automatic updates weekly. Its search index updates every five minutes. These published timings do not guarantee that every package will appear on an exact schedule. Packagist’s package management information describes how it finds versions from repository tags.

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