Engineering Practice
Is This a Breaking Change? Apply Semantic Versioning to a Real Release
A ten-change assessment applies a declared fictional API contract to defaults, output order, errors and deprecation. Actual isolated Python checks expose a rejected candidate and verify a revised one, while the completed release note keeps publication and consumer verification pending.
Decide whether a change is breaking by comparing the proposed behavior with your declared public API, including defaults, outputs and errors. Classify the changes that will actually ship together, then choose the release version. Calling something a bug fix does not establish compatibility, and adding a major number does not establish that migration is safe. Keep the contract, evidence and release decision together.
This LandOffer.ai guide applies that process to a fictional library with real, isolated Python execution. The ten-change review and release decision are authored examples. Three small implementations were actually run locally against explicit expectations; no package was downloaded, installed for consumers, published or deployed. The checks demonstrate a particular contract difference, not compatibility with every real application.

Establish the public contract before choosing a number
Semantic Versioning 2.0.0 requires a declared public API. Its core categories distinguish incompatible changes, compatible additions and compatible bug fixes. Review the contract effect even when the diff is small or the change is urgent.
For a library, inspect callable names, parameters, defaults, accepted inputs, return values and documented errors. For another product, the relevant public surface might include a command's exit behavior, an export schema or configuration keys. Specify the surface your project promises rather than assuming SemVer automatically defines every operational guarantee.
Record a baseline version and its documentation. If behavior and documentation disagree, retain both facts. A fix can restore an intended contract while disrupting callers that relied on a defect. Investigate the effect and communicate it; do not erase the old implementation or silently redefine the old promise to make classification convenient.
In the fictional LintelNames library, baseline 1.4.2 declares render_names(names, *, prefix="Name: ") and an equivalent public alias, names_text. Inputs must be lists of strings; invalid inputs raise TypeError. The result has one rendered name per line, without a trailing newline. Input order, duplicates, Unicode and name whitespace are preserved; the function does not mutate the input. An empty list is documented to return an empty string.
Those are the example's actual written promises. Private helper names and source formatting are excluded. The baseline code nevertheless returns None for an empty list: a retained defect, not a second documented empty-input mode.
Completed review: classify ten proposed changes independently
The maintainer, fictional engineer Rowan, reviews ten proposals against that baseline. Each row states the minimum classification for that isolated proposal under this project's declared contract. It is not a list of changes all included in one release. Rows describing internal or documentation work include the project's chosen packaging convention rather than a universal SemVer mandate.
| Proposal | Effect on this declared contract | Decision for the isolated proposal |
|---|---|---|
| 1. Return an empty string for an empty list | Restores the written return contract; old code returned None |
Compatible bug-fix classification: patch; disclose the behavior correction and investigate known reliance on the defect. |
2. Add keyword-only suffix="" |
Existing calls keep their output; callers can opt into additional text | Compatible addition: minor, with old default-call evidence required. |
3. Document names_text as deprecated but keep it callable |
Existing alias behavior remains; documentation directs new usage to render_names |
Minor for public deprecation; removal is a separate decision. |
4. Change the default prefix from Name: to Item: |
Existing calls without a prefix produce different output | Major if included; do not label it a minor wording improvement. |
| 5. Sort names before rendering | Violates the promise to preserve input order | Major if included, even when alphabetical output looks preferable. |
| 6. Strip leading and trailing whitespace from each name | Changes explicitly preserved content | Major if included; offer opt-in behavior separately if useful. |
7. Delete names_text |
Removes a callable public entry point | Major if included; earlier deprecation does not make removal compatible. |
8. Raise ValueError instead of TypeError for invalid inputs |
Changes the documented exception that callers may catch | Major if included; unchanged successful examples are insufficient evidence. |
| 9. Refactor the private construction of output strings | Intended to preserve all public behavior | No API change; project selects a patch for this small maintenance-only package update, contingent on checks. |
| 10. Correct a spelling mistake in explanatory documentation | No callable or behavioral promise changes | No API change; project uses a patch if distributing a new package for this correction, rather than claiming SemVer requires every website edit to bump a package. |
The npm versioning guidance presents the major, minor and patch increments and their resets for package updates. Applied here, compatible additions to 1.4.2 lead to 1.5.0; an included incompatible change would lead to 2.0.0. A release containing both a compatible feature and a fix is not classified as patch merely because most changed lines repair the bug.
Keeping a disposition for each proposal lets the maintainer remove an incompatible change without discarding the compatible work. Rowan can keep the old default and postpone the prefix redesign, rather than forcing a major release just to include an optional suffix. Conversely, if the default change is essential, a minor label cannot make it compatible.
Run old consumer expectations against the candidate
The first candidate combines the empty-input correction, the optional suffix and a changed default prefix. Rowan initially proposes a minor release. The isolated test uses an explicit old-consumer expectation:
expected = "Name: Zoe\nName: Ari"
actual = candidate.render_names(["Zoe", "Ari"])
The rejected candidate actually returns Item: Zoe\nItem: Ari. Its result differs from the stated expectation, so retaining that candidate would require an incompatible-change decision. The example records this as an expected finding in the comparison harness, not as a passing compatibility check.
The revised candidate restores prefix="Name: ", retains the empty-input correction, adds suffix="", and keeps the alias. Its candidate documentation marks the alias deprecated without adding a warning emission or promising a removal date. Old calls still use the original prefix; a caller must explicitly request a suffix.
This implementation was actually executed in Python 3.12.14. The local harness completed 15 explicit checks covering the baseline defect, the rejected mismatch and the revised behavior. The 15 checks include confirming the known baseline defect and detecting the rejected mismatch; they are not 15 passing consumer integrations. The retained trace records actual and expected values for each check.
Completed compatibility note and release decision
Rowan writes the following review record after the local execution. The fictional release ownership surrounds actual local results; it is not evidence that any real engineering team approved a release.
| Check or decision | Recorded evidence and disposition |
|---|---|
| Baseline reference | 1.4.2 authored contract and saved implementation; known empty-list result is None despite the documented empty string. |
| Rejected candidate | Default call with Zoe, Ari returns the Item: prefix. Incompatible with the declared default; excluded from the minor candidate. |
| Revised default | Same input returns Name: Zoe\nName: Ari, exactly matching the explicit expectation. |
| Ordering and duplicates | b, a, b produces three lines in that order, retaining the repeated b. |
| Content preservation | Leading/trailing whitespace and the Unicode examples 李, Zoë remain in the actual returned strings. |
| Existing entry points and errors | Custom prefix and names_text calls work; a tuple input and a list containing an integer each raise TypeError. |
| Bug fix and opt-in addition | Empty list returns ""; suffix="!" produces Name: A!\nName: B!. The checked input list remains unchanged. |
| Candidate contents | Include proposals 1, 2 and 3; exclude the breaking default, sorting, trimming, alias removal and exception change. Other maintenance proposals are not claimed as implemented. |
| Version and authority | Rowan records 1.5.0-rc.1 as the local candidate designation. Release owner Ellis accepts that classification in the fictional review; publication remains pending separate release checks. |
| Open evidence | No built distribution, dependency resolver, supported-runtime matrix, external consumer application, installation or production check was run. The example has no known-consumer investigation establishing whether anyone depends on the empty-input defect. |
The release note states: “Adds an optional suffix while preserving default formatting. Corrects empty-list output to the documented empty string. Marks names_text deprecated; the alias remains callable. The proposed default-prefix change is excluded.” It tells a reader what actually changed without burying the correction under “miscellaneous fixes.”
For a real package, assign the open checks to the relevant maintainers before release. The local evidence supports a limited classification decision; it does not clear artifact signing, package contents, runtime support or organizational approval. Where a defect has acquired substantial consumer reliance, make an explicit compatibility and communication decision rather than relying solely on the word “documented.”

Handle prefixes, prereleases and dependency ranges separately
The SemVer FAQ distinguishes a tag such as v1.5.0 from the semantic version 1.5.0; the leading v is a tag prefix. Follow the syntax expected by your own manifest, tag workflow and tooling; do not paste a convenient tag into every version field.
The proposed 1.5.0-rc.1 designation identifies a prerelease rather than the normal 1.5.0 release. It does not excuse an unnoticed breaking change in a stable API. Separately, build metadata such as +review.7 does not increase SemVer precedence. These labels communicate different information; neither substitutes for checking which code the artifact contains.
The node-semver documentation describes its parser, cleaning functions and prerelease range behavior. Its range handling ordinarily excludes prereleases unless the range explicitly opts into them in the documented way; an includePrerelease option changes that behavior. That is npm tooling context, not a claim about Python dependency selection. No resolver was executed in this exercise.
When reviewing a real consumer upgrade, inspect that consumer's actual constraint, lockfile and resolved artifact. A syntactically valid version or satisfied range answers a selection question. It does not establish that the implementation preserved every promised behavior or that an application can safely deploy it.
Keep a version decision revisable until release evidence is complete
Before merging the release decision, compare the final contents with the assessed proposals. If a later commit sorts the names, changes TypeError to ValueError or replaces the default prefix, reassess the minor decision and rerun the affected old-caller checks. Update the compatibility note when the candidate changes rather than treating the chosen number as an immutable planning commitment.
Once an actual version is released, the SemVer specification prohibits changing its contents under that same version. Preserve the released reference when correcting a mistaken classification; communicate the problem and issue an appropriate new version. In this example nothing was published, so Rowan can revise the local candidate without pretending to repair an existing registry release.
Further workplace guides are available from LandOffer.ai. For your next release, write the public promises, classify each proposed change, and retain concrete old-caller expectations and observed results. Name the owner of each outstanding check and obtain the actual release decision before treating a classified candidate as published. Compatibility is a claim to support with evidence; the version number is how you communicate that decision.
Sources and Further Reading
- Semantic Versioning 2.0.0 — declared public API, deprecation, prereleases, metadata, immutable releases and FAQ; checked October 28, 2026.
- npm Docs: About Semantic Versioning — package-update increment categories and resets; checked October 28, 2026.
- npm/node-semver: Official README — parser and range behavior, including prerelease handling; no resolver or registry test claimed.


