Skip to content

docs(standard): restate the standard as numbered requirements with BCP 14 key words - #112

Merged
lesnik512 merged 2 commits into
mainfrom
docs/standard-requirement-ids
Sep 25, 2026
Merged

lesnik512 merged 2 commits into
mainfrom
docs/standard-requirement-ids

Conversation

@lesnik512

@lesnik512 lesnik512 commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Summary

Restates the standard as numbered requirements. The page mixed normative statements with incident history, rejected designs, and facts about tools, so it read as a description of conventions rather than a standard, and the core was never delimited.

The new shape follows what published standards share (OpenSSF Best Practices criteria, Scientific Python's sp-repo-review, the GOV.UK Service Standard):

  • Every requirement has a stable ID with an anchor (#CI6), one normative sentence, and an optional Why line kept apart from it.
  • BCP 14 key words (RFC 2119 / RFC 8174), capitals only. MUST and MUST NOT form the core; SHOULD is a recommendation whose departure is explained in the PR; MAY is a permission.
  • Canonical artifacts (ruff block, AGENTS.md paragraphs) move to appendices, so the requirement list stays scannable.
  • Exemptions cite requirement IDs.

Stable IDs are also what a conformance check would key on (sp-repo-review's model: check code = requirement ID, linking to its anchor). That is a separate issue, not part of this PR.

Changes

  • docs/standard.md: 48 requirements in 11 groups (TL, JF, RF, TY, TS, PV, CI, RL, FL, RM, MD), two appendices, exemptions keyed by ID. "Changing the standard" adds two rules: IDs are never reused, and a new MUST lands first as a SHOULD with a date it becomes MUST.
  • CONTEXT.md: adds Requirement; Core is now the MUST requirements. This fixes a contradiction: CONTEXT called everything outside the core "free", the page called it "a recommendation".
  • AGENTS.md: the links to section 5 and section 11 now point at #TS2 and #metadata. No other repo in the org links to section anchors.

History is trimmed rather than moved to ADRs. The #95 rejection of a shared workflow and the floors incidents survive as Why lines on CI3 and CI6, since without them the same proposals come back. #113 (floors on pull requests only, scheduled.yml daily) is merged in as CI2 and CI6; its rationale, including the upstream-exposure argument, is condensed into CI6's Why.

Strength assigned where the old text only implied it

ID Old text Now
RF3 "target-version is omitted" SHOULD NOT set it
RL3 "there is no CI gate in the workflow" MUST NOT run checks of its own
RL6 "a conventional-commit PR title is the changelog entry" SHOULD follow Conventional Commits
FL6 "adds its own only to override" MUST NOT carry its own except to override
TS5 "the one standing exclusion" exclude_also MUST be exactly that entry

Everything else keeps its meaning.

Checklist

  • Tests pass (uv run pytest: 132 passed, 29 skipped)
  • mkdocs build --strict passes; every in-page anchor on the standard page resolves
  • Lint, type check, uv build, metadata: not applicable, docs only

@lesnik512
lesnik512 merged commit 1e42c23 into main Sep 25, 2026
3 checks passed
@lesnik512
lesnik512 deleted the docs/standard-requirement-ids branch September 25, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant