GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

§12 versus §13: v0.2 calls itself a minor bump while retiring two v0.1 fields

Open
#239 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.