docs(standard): restate the standard as numbered requirements with BCP 14 key words - #112
Merged
Merged
Conversation
…ment-ids # Conflicts: # docs/standard.md
3 tasks
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
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):
#CI6), one normative sentence, and an optional Why line kept apart from it.AGENTS.mdparagraphs) move to appendices, so the requirement list stays scannable.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#TS2and#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.ymldaily) 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
target-versionis omitted"exclude_alsoMUST be exactly that entryEverything else keeps its meaning.
Checklist
uv run pytest: 132 passed, 29 skipped)mkdocs build --strictpasses; every in-page anchor on the standard page resolvesuv build, metadata: not applicable, docs only