Writing Migration Guides for Installed Laravel Packages

Users need to do more than update the package version in Composer when a Laravel package release changes published files, application code, or stored data. A migration guide gives users instructions for a specific upgrade: what to inspect, change, and verify.

Package maintainers should list the instructions in the order users need to follow them. Name the exact versions users are upgrading between. Explain what changes in the database and its data, show old and new code when behavior changes, and finish with checks users can run. Laravel packages can copy configuration and migration files into an application. Composer does not automatically update those local copies. Laravel’s package-development documentation describes these published resources.

Name the upgrade path and affected users

Give each set of instructions a precise version range, such as “Version 2 to version 3.” State the required PHP and Laravel versions, and include any required versions of dependent packages. If users must upgrade to an intermediate version before reaching the target, say so. Do not assume they know whether they can skip a major release.

Separate Laravel framework changes from package changes. If the package release requires a Laravel framework change, name the Laravel version and link to its upgrade instructions. Laravel’s version-specific upgrade guide, for example, names affected users and shows the previous and replacement API patterns.

Next, describe what the release changes. Tell readers whether they need to change application code, published configuration, database schema, stored data, or operational components such as queue workers. Include only surfaces the release actually affects. If a conversion requires manual work, say that before users begin.

Put the migration steps in execution order

First, have users list what the upgrade will affect and protect the relevant data. Ask users to identify package files they changed after publishing them, application classes that extend package classes, and records or other data the package stores that the upgrade will affect. Tell them how to back up or otherwise protect that data before a destructive or irreversible change. If the release has no data or operational impact, say so instead of adding generic precautions.

A practical sequence for a release guide is:

1. Check compatibility. State the source and target package versions. Include the required PHP and Laravel versions and any dependency constraints.
2. Inspect local customizations. Identify the published configuration, migration files, custom models, overridden methods, implemented contracts, and references to package classes or events that the release affects.
3. Update the dependency. Provide the exact Composer command for the package and target version. Clarify whether users need to change the version constraint in composer.json.
4. Change the database. Explain whether users should run a new migration, create an application migration, compare a published migration with the new package version, or convert stored data.
5. Update application integrations. Show the required changes to configuration and code, and identify any affected routes, middleware, commands, events, listeners, or tests.
6. Validate and deploy. Give staging checks and any release-specific deployment actions, then describe what to inspect after production deployment.

Use this sequence as a structure for the guide, but include only the steps the release needs. A package with no persisted data may need no database instructions. A package that stores work in a queue backend needs operational guidance only if the release affects that state or its workers.

Explain how the package’s published migration file affects the upgrade. Users may have published it into their application before editing it or running it. Explain how the new package migration relates to that local file and to databases that already ran it. Laravel documents publishing package migrations, while the Laravel Permission upgrade guide tells users to compare migration stubs and create a new migration when needed.

Show each breaking change as an old-to-new example

If you only list renamed classes or configuration keys, users must search their code to find them and work out what to use instead. Show the old form and the required new form, then name the places readers should inspect. The following class names are schematic; replace them with the package’s real API:

// Before
use Vendor\Package\Events\RecordCreated;

// After
use Vendor\Package\Events\RecordCreatedEvent;

Tell users to update affected listeners and any code that names the old class directly. If the package retains an alias or supports both names temporarily, state the release in which that support ends.

Published configuration needs the same treatment. Users may have customized a copy in config/, so tell them whether to merge a changed default, rename a key, or remove an obsolete setting. For example:

// Before: config/acme.php
return [
    'old_option' => true,
];

// After: config/acme.php
return [
    'new_option' => true,
];

Explain whether the old key still works and what value the replacement should have. The Permission upgrade instructions also identify config files, custom models, overridden trait methods, and implemented contracts. Changes to these parts of the package can break existing applications.

Explain schema and data changes separately

A Composer update installs package code, but it does not change database tables or convert stored values by itself. State what database work the release requires: none, a migration that changes the database structure, a data conversion, a migration users must adapt by hand, or a combination. If users must write a migration, identify the old and new data locations and say whether the conversion keeps or removes the old value.

For example, a release that moves a value from a JSON column into a new column might require a migration like this:

Schema::table('package_records', function (Blueprint $table) {
    $table->json('new_value')->nullable();
});

DB::table('package_records')
    ->whereNull('new_value')
    ->update([
        'new_value' => DB::raw(
            "JSON_EXTRACT(old_json, '$.new_value')"
        ),
    ]);

This is an illustrative pattern, not portable SQL for every database. The guide should name the database systems that support this conversion and provide tested versions of the conversion where needed. It should also explain how null and empty values behave, whether the original JSON value remains, and how users can check the result. The Media Library upgrade guide illustrates the level of specificity needed when a release adds a column and moves existing JSON data.

Do not promise that a rollback restores converted data unless it actually does. If users need a manual conversion or the package provides no automatic conversion, state that plainly and explain what application-specific work remains.

Tell users what to verify

Tie every check to a change described earlier. In staging, users should confirm that Composer can install the package with the stated PHP and Laravel versions, and that the database has the tables and columns the target release expects. When the release moves data, have them inspect representative old records, including null or empty cases, and confirm the old value was retained or removed as documented.

Users should compare their published configuration with the target defaults and exercise behavior controlled by changed settings. They should run tests for custom models and implemented contracts. They should also test overridden methods, event listeners, and renamed references. When old records remain in use, test those records as well as newly created ones.

Finally, name operational checks only when the package needs them. If the change affects long-running queue workers, tell users whether to restart them and what behavior to test afterward. If the package has no such dependency, avoid generic restart instructions. Ask users to check logs for errors related to the changed package code and to verify the package’s main behavior after deployment.

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