GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
§12 versus §13: v0.2 calls itself a minor bump while retiring two v0.1 fields
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
§12 defines what each kind of bump may contain:
> - A **minor** version bump introduces backward-compatible additions (new optional fields, new conventional section headings).
> - A **major** version bump may make breaking changes (renaming required fields, changing reserved filenames).
§13 then classifies v0.2 against that rule and carves out an exception in the same sentence:
> v0.2 supersedes OKF v0.1 and is a minor version bump under §12, except for two deliberate breaking changes called out below because they rename or retire v0.1 fields.
The two are `timestamp`, superseded by `generated.at`, and the body `# Citations` list, superseded by `sources` (§13.1).
The same framing appears in the migration PR (#227), which describes v0.2 as "an additive, backward-compatible minor version" and two paragraphs later as carrying "Two deliberate renames".
## Why it matters
§12 gives a consumer one thing to key off, the `okf_version` a bundle declares. If a minor bump can retire a field, a consumer reading `okf_version: "0.3"` learns nothing about whether the fields it depends on still exist. The number stops carrying the compatibility guarantee §12 sets it up to carry.
## How strong this is
§12 says a major bump "may make breaking changes", which is permissive rather than exclusive, so §12 never literally forbids a breaking minor bump. The inconsistency is with §12's definition of a minor bump as "backward-compatible additions", not with a MUST. Worth stating plainly so the finding is not read as stronger than it is.
## Possible resolutions
- Classify v0.2 as a major bump.
- Keep the version and widen §12, so a minor bump may retire a field when a documented consumer fallback exists. §13.1 already supplies both fallbacks.
- Keep both and say in §12 that the distinction is advisory, so no consumer builds on it.
I don't have a preference between these. What's hard to build against is a text that states a rule and an exception to it in the same breath, without amending the rule. Possibly I'm reading §12 more strictly than it was meant.
Contributor guide
Research direction
Read §12 and §13, especially §13.1, alongside migration PR #227 to understand the versioning rule and the two field changes. Determine which of the listed resolutions the maintainers accept, then make the specification state one consistent compatibility policy and ensure the v0.2 treatment is unambiguous.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100