Skip to content

Guard the spec classification in the published docs #76

Open

Description

@mroderick

A review of #75 found five non-blocking gaps in the classification. The split itself is correct: 49 scenarios, 13 draft across 2.1/2.6/2.7, 36 library, and the embedded gherkin matches the feature file at head. These are the guardrails and wording issues left after the merge.

  • The @draft set asserts the library's section URI. Five of the seven 2.7 scenarios assert the response body should contain "section-2.x". The draft's own 2.7 examples use type: https://developer.example.com/idempotency, and section-2. appears nowhere in draft-07. An implementation that meets 2.7 with its own problem type fails the draft selection. Cheapest fix: say in the 2.1 and 2.7 Rule prose that the section-2.x type token is this library's convention while status, content type and the presence of type/title/detail come from the draft. Moving the assertions into @library changes assertions, which docs(spec): classify scenarios as draft requirements or library policy #75 declared out of scope.
  • The gherkin in docs/specs/index.md is hand-synced. The fence duplicates the whole feature file and website CI runs only lint, commitlint, prettier and link checks. Add a CI step that extracts the fence body and diffs it against docs/specs/idempotency.feature.
  • The overview counts are hand-computed prose. The 13 of the 49 and per-Rule bullets are not checked anywhere. Parse the feature file's Rule tags in a website check and assert the figures, or generate the bullets at build time.
  • The tag structure is never exercised where it is authored. Website CI does not parse or dry-run the feature file, so --tags @draft selecting 13 is only proven in idempot-js after a sync. Run the classification checker or a cucumber dry-run in website CI.
  • The @draft prologues say "requires" where the draft says SHOULD. Lines 28 and 67 read "The draft requires ..." while draft-07 uses "The resource SHOULD ...". Line 17's 2.1 MUST wording is accurate. Change "requires" to "says the resource should" in the 2.6 and 2.7 prologues.

Source review: pi-review on #75 (correctness, testing, adversarial, plus an independent validator). Non-blocking for the merge, so tracked here rather than reopening #75.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions