Backporting Fixes to Older Laravel Package Releases

Laravel package maintainers sometimes need to fix a defect for users who cannot upgrade to the newest package line. A backport is a fix adapted for an older release line that the package still supports. A release line is a related series of package versions, such as patch releases within the same major and minor version.

A backport is justified when the package’s support policy covers that line, the defect affects it, and maintainers can test a compatible fix. To backport a fix, maintainers choose the target branch, check that the fix works with that line’s Laravel and PHP requirements, publish a new version, and update the documentation for users of that line.

Set the support policy before choosing a fix

A package’s own support policy determines which older releases receive fixes. Laravel framework support dates do not automatically define support for independently maintained packages. Laravel’s Laravel 10 release notes, for example, distinguish the framework’s support periods from the treatment of additional libraries. Those details apply to the Laravel 10 documentation and should not be treated as a universal rule for third-party packages.

Publish which Laravel and PHP versions each package line supports, and how long maintainers will support it. Specify whether support includes ordinary bug fixes, security fixes only, or no further releases. Tell users where to move when a line reaches end of support. A short support table in the README can make these commitments easy to find.

Backport a fix when the line remains supported, maintainers can reproduce the defect on it, and they can test a focused change against its dependencies. Prioritize security issues based on how severe they are and how widely they affect users. State plainly when an older line will not receive a fix or when a remedy requires a compatibility break.

Keep patch releases narrow. A correction to existing behavior belongs in a patch release when it preserves the public API, meaning the functions and behavior package users rely on. A new feature or broad refactor usually deserves a different release type because it introduces changes beyond the correction. The Semantic Versioning rules describe patch versions as backward-compatible bug fixes, minor versions as backward-compatible additions, and major versions as incompatible public API changes.

Other projects illustrate why maintainers should define their own threshold. Symfony’s maintenance policy restricts changes in patch releases, while Kubernetes’ policy considers severity and feasibility when deciding which fixes to backport. These are project-specific policies, not Laravel package requirements.

Choose a branch flow and adapt the fix

A maintenance branch is a Git branch that carries ongoing fixes for a supported release line. For example, a package might keep its current development branch and separate maintenance branches for older supported lines. A release tag marks one specific code state so package managers can identify and install that version.

Choose and document how fixes move between branches. Maintainers can start with the oldest maintained branch where the defect exists, then merge the correction into newer branches. Symfony’s contribution guidance uses this oldest-branch-first approach. Another option is to fix the current development line first and then backport selectively. Either approach works as long as maintainers apply the fix to every supported line it affects.

Git’s cherry-pick command applies the changes from a selected commit to another branch and creates a new commit there. It does not merge all history from the source branch. The Git documentation describes using -x to record the source commit in the new commit message, which helps maintainers trace fixes across public branches. If the older code has different APIs or dependencies, adapt the change rather than forcing an identical patch onto it.

A clean cherry-pick confirms only that Git applied the changes. It does not show that the fix works with the older branch’s Laravel version, PHP version, or dependency constraints. Add a regression test, which checks that the specific defect stays fixed, and run it on the destination branch before preparing a release.

Test the combinations the package promises

Test the backport against the Laravel and PHP versions listed in the package’s support policy. Tests that pass only on the newest line leave older lines unvalidated.

Laravel’s package development documentation describes using Orchestra Testbench to test a package in a Laravel-like environment. Testbench compatibility depends on the Laravel version, so maintainers should check that their test harness fits the line under test. Its compatibility documentation shows which Testbench versions correspond to several Laravel versions. Those mappings do not establish support for any particular package.

Continuous integration (CI) jobs can run the regression test across the combinations the package commits to support. Cover relevant Laravel versions and PHP versions, as well as dependency variations that change across those lines. The full matrix depends on the package’s stated support and the risk of the change; maintainers should distinguish required release checks from broader compatibility tests.

Publish a new patch tag for the older line

Composer uses version tags to resolve stable package releases. A branch moves as development continues; a tag marks a fixed version. Composer also supports branch aliases, which let a development branch satisfy certain development-version constraints. An alias does not publish a stable release for users who need a tagged version. The Composer version documentation explains how Composer handles tags, branches, and constraints.

After testing the maintenance-branch commit, publish the next valid patch version on that line. Do not move or reuse a tag that users may already have installed. Before release, confirm that the tag points to the tested commit and that the package’s Composer constraints still fit the Laravel and PHP versions the release targets. Release notes should identify the package line and summarize the correction. They should also mention any prerequisite or remaining limitation.

If maintainers publish through GitHub Releases, they should select the intended tag and the branch containing the release code. GitHub’s release documentation describes that workflow. When maintainers enable immutable releases, they can review a draft and check the release details before publishing.

Keep older-line documentation current

Update the documentation users of the affected line are likely to consult. Record the release in the changelog and state whether the fix applies to that line. Explain any workaround users should remove or prerequisite they must meet. If documentation differs between package lines, update the matching versioned documentation rather than changing only the newest page.

Keep support status, installation guidance, and release notes consistent. If a line has reached end of support, say so and point users to a supported alternative. Symfony’s contribution guidance offers one project-specific example of connecting code changes with relevant changelog and upgrade documentation; package maintainers can use the same principle without adopting Symfony’s exact documentation structure.

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