Gating Unfinished Features in Laravel Packages

Laravel package maintainers choose which code users receive by selecting a Git commit for each release. A tag is a name for a specific Git commit. Composer package registries such as Packagist use repository tags to identify package versions. To gate a release, maintainers check that the selected commit contains only work approved for that version.

Keep unfinished code out of a stable release by tagging a commit that excludes it. A feature flag keeps code in the package while turning its behavior off, and a beta tag lets opt-in users install a pre-release. Feature flags and beta tags leave that code in the tagged version. The distinction matters when you decide what to publish, what to test, and how to describe work you have postponed.

Choose a release commit without unfinished work

A release tag determines the source associated with a package version. Packagist fetches versions from repository tags, so a GitHub release page or a setting in composer.json does not remove code from the commit the tag points to. Packagist also recommends letting repository tags and branches supply version information rather than setting a separate version field in the manifest. See Packagist’s version guidance.

Before tagging, identify the exact commit you intend to ship and review its changes against the previous release. If the development branch includes unfinished work, choose an earlier ready commit, create a release branch that excludes the work, or remove the unfinished changes from the candidate commit. The release decision belongs to the contents of that commit, not to whether the main branch feels ready.

A development branch provides another way to distribute code. Packagist makes branches available as development versions. Composer’s default minimum-stability setting accepts stable versions unless a project that installs the package opts into less stable versions. That means work absent from the next stable release can still be available to developers installing a public development branch. If the feature must be unavailable to all external consumers, review those development versions and any other distribution channels too. Composer documents its stability levels and configuration.

Use a pre-release tag when you want opt-in users to test a version. Semantic Versioning treats identifiers such as alpha, beta, and release candidate as pre-release versions. These versions rank below the corresponding stable version. A pre-release is still a published version containing its tagged code. If the feature must be absent from every tagged version, exclude it from the tagged commit; a pre-release label does not provide that boundary. See the Semantic Versioning rules.

A feature flag serves a different purpose: it controls whether shipped code runs. Use one when the implementation is ready to ship but should remain inactive by default. When the implementation itself is unfinished and should not be part of the release, select a commit that does not contain it.

Verify the version you are about to publish

Run checks against the release candidate, the exact source you plan to tag. A passing test run on a developer’s working tree does not show that the tagged commit contains the same code. Review the changes in the release candidate and confirm that tests do not depend on uncommitted files or package paths that exist only on a local machine.

A practical pre-publication check includes:

• Run composer validate to check the package manifest, as Packagist recommends.
• Check that the tag name follows a version format Packagist accepts, such as X.Y.Z or vX.Y.Z, with an appropriate pre-release suffix when needed.
• Run the package test suite against the candidate. For tests that need a Laravel framework environment, Laravel’s package documentation points to Orchestral Testbench.
• Verify the package metadata and integration points that the release uses. Check service-provider discovery, configuration, routes, commands, migrations, views, or assets.
• Compare the release notes with the candidate’s contents. Remove claims about features that are postponed or absent.

The exact integration checks depend on the package. Laravel’s package development documentation describes package concerns and testing with Testbench; maintainers should test the features their own users will install and call.

Once Packagist publishes a stable version, its source and distribution references are locked. If a release contains a mistake, publish a new version with the fix instead of moving or rewriting the published tag. See Packagist’s version immutability guidance.

Describe postponed work without promising a release

Keep release notes focused on what the version contains. A changelog’s Unreleased section tracks changes intended for an upcoming release. Maintainers move those entries into a versioned section when they publish that release. Keep a Changelog recommends writing for readers rather than copying the commit history.

Put deliberately deferred work in an issue, roadmap, or development note instead of presenting it as an upcoming change. Name the feature and its status, then explain what users can do now and what remains unsupported. If a reason helps users understand the decision, state it briefly, such as unresolved compatibility or testing work. Link to a tracking issue when one exists, and avoid promising a version or date unless you are prepared to meet it.

Be explicit about the feature’s state. Say whether the implementation is absent from the release, included but disabled, or available only in a pre-release. Those descriptions tell users what they can install and what behavior they should expect; a vague note that a feature is “coming soon” does not.

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