Keeping Laravel Package Documentation Up to Date

When you maintain a Laravel package, a code change can make its README or configuration instructions wrong. Users rely on those instructions to install the package, set options, and call its public features. A public API is the set of methods, commands, configuration options, and behaviors that users are expected to rely on. The Semantic Versioning specification recognizes that documentation can define part of that API.

Review documentation alongside code whenever a change affects how users configure or use the package. Check configuration instructions, new or changed APIs, removed behavior, and examples that depend on the changed code. This review keeps the documented behavior aligned with what the package actually does.

Review configuration changes against Laravel’s behavior

When you add or change a configuration option, document its key, default value, accepted value, and effect. Also explain whether users need to publish the package’s configuration file and whether the publishing command or tag changed.

Laravel’s package-development guide describes a common setup. In boot, a service provider tells Laravel which configuration files users can publish. In register, it merges the package’s default configuration. The guide also explains two details that affect documentation. First, mergeConfigFrom merges only top-level array keys. If a user’s published configuration includes a nested array, this method does not fill in missing defaults inside that array. Second, Laravel cannot store configuration closures in the cached configuration created by config:cache. The Laravel package guide covers these behaviors.

Those details matter when users keep a published configuration file in their application. If the package adds an option inside a nested array, explain whether users must add it to an existing configuration file or whether the package handles a missing option another way. Make sure examples also reflect any configuration-caching constraints. If the package uses a helper such as Spatie’s Laravel Package Tools, follow its configuration conventions, which apply to packages using that tool rather than to every Laravel package.

Document new APIs and compatibility changes

When you add or change a feature that users interact with, update its explanation and example. Describe required arguments, the result or effect, and any constraints that affect use. Check each example against the actual method signature and the package versions it claims to support.

When a package follows SemVer, backward-compatible public API additions and deprecations call for a minor-version increment, while backward-incompatible public API changes call for a major-version increment. The package’s compatibility policy should define which behavior counts as public. A refactor that leaves user-visible behavior unchanged may not need a documentation edit; a changed method signature or usage contract does.

Give deprecated behavior a clear path forward. Tell users what replaces the old method, option, or command, and identify the package version in which removal is expected if the package has set that timeline. Keep removal and breaking-change details in the release notes as well as in upgrade instructions. Keep a Changelog recommends recording deprecations before removal, but no universal deprecation period applies to every third-party Laravel package. State the schedule your package supports.

Keep README examples tied to working code

A README snippet can look plausible even if it uses a method that has been renamed or setup steps that are outdated. It may also refer to an option the current package no longer supports. When code changes, search the README and other documentation for the changed names and usage patterns. Update every affected example, and make clear which package or Laravel versions the instructions cover.

For substantial PHP examples, consider putting the code in a test or small example file that runs against the package. Orchestra Testbench provides a Laravel-like environment for package tests and documents how to load a package service provider. That helps verify package integration, but it does not check whether the Markdown examples match the code. Treat executable examples as a maintainer-created safeguard, and make sure the test covers the behavior the example demonstrates.

Keep the README focused on the installation and first-use information readers need most. If detailed instructions live elsewhere, link to them clearly and remove conflicting copies. A pull-request template can ask contributors to report how their changes affect documentation. GitHub explains templates and review routing in its pull request guidance. A prompt helps reviewers notice missing updates, while tests verify only the examples they actually exercise.

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