When to Update Your Laravel Package Documentation

When you maintain a Laravel package, update its documentation whenever a code change affects what users can do, configure, or run, or changes the results they should expect. This includes changes to PHP methods, setup steps, configuration, commands, and database changes, because users rely on those details when they use the package.

Laravel packages can expose configuration, routes, migrations, and commands. Changes to these features affect how an application uses the package. Review the documentation whenever you change code, and update it in the same pull request when users need new or corrected instructions.

Update docs when the user-facing contract changes

Update the documentation when a PHP method's name or arguments change. Also update it when users must edit code or change a setting. Do the same when they must run a database migration or respond to a different result. Explain what changed and what users need to do.

When a code change affects users, update the docs in the same pull request. This keeps the instructions in step with the code and lets reviewers assess both. You do not need to edit the docs when you rename a private helper or refactor internal code without changing documented behavior. The Google documentation guidance recommends keeping docs current with code changes and avoiding edits that do not help users.

API changes

Update API references and examples when users call a new or changed method, Laravel facade, route, or Artisan command. For example, if Report::generate($range) now requires another argument, update examples with the old call and explain what users must pass. If a method or command option gets a new name, document the replacement.

When you deprecate an API, explain what users should use instead. If you plan to remove it, say which release will include the removal when you know. Under Semantic Versioning, a backward-incompatible change to a declared public API requires a major-version release. The package’s documentation also helps users understand which interfaces are public.

Configuration changes

Update the configuration reference and sample file when you add or remove a setting. Make the same updates if its name or default changes, its meaning changes, or it accepts different values. If an environment variable sets that option, update the variable’s name and instructions too.

Take care when users publish a package’s configuration into their Laravel application. Laravel’s package development documentation explains how packages publish configuration. The published file is separate from the defaults inside the package, so tell existing users whether to edit their file or publish a new one. Document the publishing path or tag your package defines. Do not suggest that a file users have already published updates when the package changes.

Migration changes

Update installation or upgrade instructions when users need a new database migration, a schema change, or a conversion of existing data. Explain what the migration changes and how users apply it using the method your package provides. Laravel’s package documentation describes loading package migrations and publishing them. Give instructions for the approach your package uses.

Check the migration code for effects users need to plan for. If it removes a database column, changes existing data, or requires steps in a certain order, explain the impact and the upgrade sequence. Do not call a migration harmless just because Laravel runs it as a migration.

Behavior changes

Update usage instructions when a documented call starts producing a different result, side effect, exception, access decision, or default. For example, if a method that returned an empty collection now throws an exception when no records match, explain the change and how users should handle it.

If existing users must change code or configuration, explain what to do in the upgrade or release notes and on the relevant usage page. State whether the package changed its behavior or the old documentation was inaccurate. An undocumented behavior change breaks compatibility only if it conflicts with the package’s stated contract or with behavior users reasonably rely on.

Put each update where users need it

When setup steps or prerequisites change, revise the installation instructions. In the configuration reference, list option names and defaults, and explain which environment variables set each option. Update API pages and examples that show users how to call methods, routes, and commands. Use upgrade notes to explain what users must do when they move to another package version. Use release notes to describe deprecations, removals, and behavior changes.

Laravel’s upgrade guides show how to describe breaking changes and their effects. Packages may choose their own format, as long as users can find what changed and what they need to do.

Before merging a change, check whether users must change their code, configuration, data, setup, or deployment, and whether existing examples still work. Update the relevant page when users need to do something differently. If no documentation update is needed, briefly explain why in the pull request when reviewers might expect one.

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