docs: write down what counts as a breaking change - #223
Merged
Conversation
For a library whose product is the types it infers, the usual reading of semver is not enough. "No runtime signature changed, so it is a patch" would let a release break every dependent build, because the inferred row shape is the API just as much as the exported functions are. VERSIONING.md states the three covered surfaces (runtime exports, inferred types, the CLI contract) and classifies changes against them. It also spells out the three cases that can turn a green build red in a minor release, and why each one is worth it: - unknown resolving to a concrete type, since freezing every unknown would freeze the entire point of the library; - strict mode reporting a mistake it used to let through, since a strict mode frozen on release day stops being useful; - a generate type mapping corrected to match what the driver really returns, since the old type was a lie the type system was hiding. Everything else that can break a build waits for a major, and the parser internals, QueryTypeError message text, CLI phrasing and compile cost are explicitly outside the policy. The policy takes effect at 1.0. Until then the 0.x rules still apply.
tiagolauer
force-pushed
the
feat/type-instantiation-budget
branch
from
July 28, 2026 17:03
fe6f421 to
f8069f9
Compare
tiagolauer
force-pushed
the
docs/versioning-policy
branch
from
July 28, 2026 17:03
e4fc579 to
c44b61c
Compare
Base automatically changed from
feat/type-instantiation-budget
to
fix/pin-typescript-5
July 28, 2026 17:08
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Third of four. Stacked on #222.
For a library whose product is the types it infers, the usual reading of semver isn't enough. "No runtime signature changed, so it's a patch" would let a release break every dependent build, because the inferred row shape is the API just as much as the exported functions are.
VERSIONING.mdnames the three covered surfaces — runtime exports, inferred types, the CLI contract — and classifies changes against them.The interesting part is the three cases that can turn a green build red in a minor, each with the reasoning spelled out:
unknownresolving to a concrete type. Freezing everyunknownwould freeze the whole point of the library.generatetype mapping corrected to match what the driver really returns. The old type was a lie the type system was hiding.Everything else that can break a build waits for a major. Parser internals,
QueryTypeErrormessage text, CLI phrasing and compile cost are explicitly outside the policy.Takes effect at 1.0; until then 0.x rules still apply.