Validating Create vs. Update Requests in Laravel
When a Laravel endpoint creates a database record, it often needs every field required for a valid record. When it updates a…
Categories
Writing a Package FAQ for Versioning and Compatibility
Package users need to know whether a release fits their project, what an update changes, and what they must do to upgrade. A useful FAQ answers those decisions in a few sentences and points to the detailed source of truth, such as release notes, a compatibility matrix, or a migration guide.
Start by defining the package’s public API: the functions, commands, or interfaces users are meant to rely on. Semantic Versioning, or SemVer, uses major, minor, and patch numbers to describe changes to that API. The convention assigns breaking API changes to major releases, backward-compatible features to minor releases, and backward-compatible fixes to patch releases. Your FAQ should explain how your package applies those rules and what kinds of compatibility it actually supports.
Define the promise behind each version
A version number promises compatibility only when maintainers say what it covers. State whether it applies to the public API, a command-line interface, a plugin interface, or another named surface. Identify experimental features or internal interfaces that fall outside the commitment.
For example, “minor releases preserve the public API” is more useful than “we follow SemVer” if you also explain what counts as public. Say whether a changed default, altered error behavior, or removed command option counts as a breaking change when users rely on those behaviors. Link the explanation to the project’s versioning policy or migration documentation, rather than repeating every detail in the FAQ.
Treat pre-1.0 releases carefully. SemVer says users should not consider a 0.y.z API stable. Cargo uses different compatibility rules: it treats the first nonzero number in a version as the compatibility boundary. If your package targets Cargo, explain the behavior users will encounter under Cargo’s compatibility rules instead of implying every ecosystem interprets pre-1.0 versions the same way.
A package can be compatible in several ways. API compatibility concerns whether existing code still works. Runtime and platform compatibility concern supported language versions, operating systems, and processor architectures. Dependency compatibility concerns which other packages work with a release. A versioning FAQ should name the dimension it addresses and distinguish a formal support commitment from a configuration that maintainers have tested.
Explain ranges and updates in the package’s ecosystem
Users need the package manager’s exact version-range syntax to see which versions it permits; calling a release “compatible” does not specify the range. Range rules differ across ecosystems. For example, npm documents ^1.0.4 and ~1.0.4 as different ranges, while Python’s ~= compatible-release operator has bounds that depend on the number of version components. Use the syntax users need for your package and explain what versions it permits. See the npm range rules or Python version specifiers for examples specific to those ecosystems.
Keep three claims separate: what a dependency range permits, what your metadata declares, and what your project tests. A range in package metadata does not prove that maintainers tested every combination it allows. Publish tested runtime and platform combinations in a maintained matrix, then link to it from the FAQ. If the package imposes a narrow dependency bound, state the reason and affected release rather than leaving users to infer whether the constraint is intentional.
Explain what the package manager's update command changes. For npm, npm update respects the package’s declared SemVer constraints; by default, it does not change direct dependency range values in package.json. Tell users where to find the release notes for the version they are moving to, and point them to the package manager’s update behavior when the command itself is part of the question.
Answer the questions users need to decide
The questions below cover common choices users face. They are not ranked by frequency. Replace bracketed text with verified package policy. Keep each answer brief, then link to the document that carries the detail.
| User question | Concise answer pattern |
|---|---|
| Which version should I use? | “For new projects, use [current stable version or range]. See the release notes for changes in that release.” |
| Is the API stable? | “Our compatibility commitment covers [named public interface]. [Experimental or internal interfaces] are outside that commitment.” |
| What counts as a breaking change? | “We treat [specific change types] as breaking. The migration guide lists changes that require code updates.” |
| What do patch, minor, and major releases mean here? | “Patches contain [scope], minors add [scope], and majors may include [scope]. This policy applies to [named interface or versions].” |
| Which runtimes and platforms does this release support? | “This release supports [runtime range] on [platforms and architectures]. The compatibility matrix lists tested combinations and exceptions.” |
| Which dependency versions does it support? | “This release requires [dependency and range]. See the dependency requirements for exact constraints and optional integrations.” |
| Can I update without changing my code? | “Updates within [specified range] are intended to preserve [defined compatibility surface]. For changes outside that range, review the release notes and migration guide.” |
| How do I upgrade from an older major version? | “For an upgrade from [old version], follow [essential step]. The version-specific migration guide lists required edits.” |
| Are prereleases suitable for production? | “[Alpha, beta, or release-candidate] builds are intended for [stated use]. Production support begins with [condition or release].” |
| How long are older versions supported? | “We provide [bug or security support] for [versions] until [date or condition]. See the support policy for end-of-support details.” |
Do not fill a blank with an assumption. If maintainers have not promised support for a runtime, platform, or older release, say what is known and direct users to the tested configurations or release policy. In particular, avoid calling a configuration “supported” when the only evidence is that package metadata allows it.
Keep the FAQ separate from the README’s instructions
The README should help a new user understand what the package does and get started. The FAQ should resolve questions that arise when users choose versions, check compatibility, or plan upgrades. GitHub’s README guidance likewise positions the README as a project starting point, with longer documentation elsewhere.
Start each answer with the version, boundary, or action. Add one sentence of qualification if needed, then link to the relevant detail. For example, a runtime answer should give the supported range and link to the compatibility matrix, rather than copying the matrix into the FAQ. An upgrade answer should identify the migration path and link to the version-specific guide, rather than reproducing its full sequence of changes.
Review links and version claims whenever a release changes the support matrix, dependency bounds, or maintenance policy. Keep released package contents fixed. If you need to correct a published release, issue a new version and identify the affected release in its notes.
What I'm buildingDelegate 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