Writing Clear Package Compatibility Notes

When package maintainers describe which language or tool versions their code supports, users need to know what they can install, what the maintainers have tested, and how long they plan to provide fixes. A version constraint is a rule that names allowed versions, such as >=3.9. That rule does not, by itself, say which versions the maintainers tested or how long they will support them.

State each claim separately. Explain each constraint in ordinary language, name any exceptions, and say what happens when a user’s version falls outside the range. Readers can then understand the limit without decoding version syntax or guessing what “supported” means.

Translate version constraints into user-facing language

Name the product or runtime first, then state the minimum version or range in plain language. For example, >=3.9 means “Python 3.9 or later.” Keep the exact constraint nearby for readers and tools that need it.

Spell out any excluded versions and upper limits instead of leaving users to interpret the punctuation. In Python version specifiers, ~=3.1 allows versions from 3.1 onward but excludes 4.0 and later. The specifier ~=3.1.2 excludes 3.2.0 and later. The version specifier rules explain these differences.

Explain what the rule does in the relevant ecosystem. Python’s Requires-Python metadata lists compatible Python versions and can help installers choose a distribution, according to the core metadata specification. npm handles its engines field differently. For dependencies, npm treats the requirement as advisory by default and warns unless the user enables engine-strict, as described in the npm package.json documentation. Cargo’s rust-version field names a package’s minimum supported Rust version. Cargo can report an error when a user runs an unsupported toolchain, and the value also affects some dependency selection, according to The Cargo Book. Tell users whether a mismatch blocks installation, triggers a warning, causes compilation to fail, or falls outside the maintainers’ support policy.

Separate requirements, tests, and support

A declared requirement sets the versions that meet its rule, while a tested range covers the versions maintainers have checked. The support policy says which versions they intend to keep supporting. These ranges can differ, so label each one separately.

For example, a package might require Python 3.9 or later but test only the Python versions in its continuous integration matrix, the list of versions its automated tests run against. State both the requirement and the tested versions, and link to the matrix. A constraint with no upper limit does not mean maintainers have tested every later Python release. Name the tested range or selected versions.

Use “supported” with a project-specific meaning. It might mean that maintainers accept bug reports, provide fixes, or include a version in routine testing. If those commitments differ, state them separately. A version that meets the package’s metadata requirement is not automatically part of the tested range or entitled to ongoing fixes.

Explain how the support window moves

A support window states how long a project maintains compatibility or provides fixes. Explain the rule that sets the window and what happens when a version leaves it. If the window moves over time, describe what triggers the change instead of giving a date that will become outdated.

The Go project supports a major Go release until two newer major releases exist. It may also issue critical fixes, including security fixes, for supported releases. This rule applies to Go’s release policy, not to every package written in Go. The Go release policy shows how a project can describe a window that moves over time. Package maintainers should publish their own rule and say whether maintenance or security fixes stop when a version leaves the window.

When a package stops supporting a runtime or platform, name the release that changes the compatibility boundary and say who the change affects. The Python Packaging User Guide’s advice on dropping older Python versions recommends making each compatibility change in its own release. Maintainers should also say whether users can still get an earlier package release. Make clear that its availability does not mean maintainers still maintain it.

Make the note match the project’s versioning policy

Readers may use version numbers to judge compatibility, but the numbers promise something only when the project follows a clear policy. Semantic Versioning defines what major, minor, and patch releases mean under its rules. Many Python projects use similar conventions without following them strictly, as the Python Packaging User Guide’s versioning discussion explains. If your project uses version numbers differently, explain that where readers need to know.

Before publishing a compatibility note, check its wording against the package metadata and current test coverage. A concise note can state the runtime requirement in plain language, show the exact constraint, name the tested versions, and link to the test matrix. If the support rule differs from the declared requirement, explain the rule and what it means for users. Record when maintainers checked the information if it can become outdated, and update the note when a release changes the boundary.

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