docs: mandate spec document's own version literals match spec/version.json (§19.5) - #185
Merged
Merged
Conversation
….json (§19.5) Adds §19.5 "This document's own version literals": the spec document's own text (§12.1/§12.2/§12.4/§17.2/§20.6 spec_version examples, §13.5's Docker LABEL example, §19.4's Current-version line and Go/C++/Rust snippets) MUST match spec/version.json, with this repository's own CI enforcing it — closing the spec's own instance of the exact hand-copied- literal drift Requirement 14 already asks every implementation to avoid. Reference implementation: TestSpecVersionMatchesVersionJSON and TestSpecDocumentVersionLiteralsMatchVersionJSON (version_consistency_test.go) read spec/version.json and spec/relay-spec.md via the package's own embedded evidence and fail on any drift across all 12 checked literals (5 named anchors + 7 spec_version example occurrences). New REQ-RELAY-100, tagged in evidence.go where the two embedded artifacts originate. Mutation-tested: bumped spec/version.json to a throwaway value and confirmed both tests failed with a precise per-literal diff; separately reworded one anchor's surrounding prose and confirmed the test reports 'pattern not found' rather than silently passing. Both restored, re-verified green. Not a relay conform check and no new §17 Requirement — this is a repository-CI-verified discipline on the spec document itself, alongside Requirements 13/14, with no change to implementation-facing obligations. PATCH (v2.7 -> v2.7.1); SpecVersion unchanged. Closes #144 Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
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
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.
Summary
Closes #144 (NEW-SPEC-6). Adds §19.5 "This document's own version
literals" and the CI mechanism that enforces it: the spec document's
own text must never drift from
spec/version.jsonthe way its"0.1"example literals once did (fixed by hand in v2.2.3).Background
Requirement 14 (§17) already obligates an implementation's declared
spec_versionto trace back tospec/version.jsonrather than ahand-copied literal kept in sync by memory. This repository's own
spec document was never held to the same standard for its own text —
§12.1/§12.2's JSON examples and §13.5's Docker
LABELexample driftedto
"0.1", three major versions stale, before being manually fixed inv2.2.3. That fix closed the immediate symptom but not the underlying
gap: nothing stopped it from recurring.
What's added
document's own text — the
"spec_version"examples (§12.1, §12.2,§12.4, §17.2, §20.6), the
LABEL io.relay.spec-versionexample(§13.5), and §19.4's "Current version" line and Go/C++/Rust snippets
— matches
spec/version.json, with this repository's own CIenforcing it.
TestSpecVersionMatchesVersionJSONandTestSpecDocumentVersionLiteralsMatchVersionJSON(
version_consistency_test.go): readspec/version.jsonandspec/relay-spec.mdvia the package's own embedded evidence(
evidence.go) and fail the build on any drift across all 12checked literals (5 named anchors + 7
spec_versionexampleoccurrences).
REQ-RELAY-100, tagged inevidence.gowhere the two embeddedartifacts (
spec/version.json,spec/relay-spec.md) originate.relay conformcheck and no new §17 Requirement.relay conformverifies binaries, not the spec document thatdefines it — this is a repository-CI-verified discipline alongside
Requirements 13/14, with no change to implementation-facing
obligations.
Version
PATCH (v2.7 → v2.7.1) — doc addition, no normative change to existing
conformant implementations.
SpecVersionunchanged.Verification
go build/vet/testclean,gofmt -l .clean,golangci-lint run0issues
gofusa check0 errors/PASS,gofusa trace -req-coverage 100100%/100% (100/100 requirements traced)
spec/version.jsonto a throwaway value andconfirmed both tests failed with a precise per-literal diff for all
12 checked literals; separately reworded one anchor's surrounding
prose and confirmed the test reports "pattern not found" rather than
silently passing (guards against the anchors going stale
themselves). Both restored, re-verified green.