docs: restore specification overview section order - #823
Open
amithanda wants to merge 1 commit into
Open
Conversation
The overview page opened with ~780 lines of deep normative detail (Quantities and units, Request Constraints, Actions) before the reader reached the architectural introduction, because each of those sections was inserted at the top of the file, immediately after "Schema notes": - Actions (#582) inserted at line 34 - Quantities and units (#653) inserted at line 34 - Request Constraints (#655) inserted at line 175 Each insertion was individually reasonable, since these are foundational cross-cutting primitives, but the sequence stacked them ahead of "Discovery, Governance, and Negotiation", which is the actual entry point for a first-time reader. This is visible on /latest but not on /2026-04-08, which predates all three. Move the three sections to sit alongside Policies after "Standard Capabilities", following the precedent set by #572, which placed the first of these cross-cutting primitives there. This restores the opening reading order of the 2026-04-08 release and groups all four core primitives together. Pure reorder: no prose edits and no heading level changes, verified by comparing the sorted line multiset against the parent commit. All 142 heading anchors are preserved, so the 20+ pages that deep-link into #quantities-and-units, #request-constraints and #actions are unaffected.
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.
The specification overview opened with ~780 lines of deep normative detail
before the reader reached the architectural introduction. Anyone landing on
the spec met "Quantities and units" as their first content.
This happened because three PRs each inserted a new cross-cutting primitive at
the top of the file, immediately after "Schema notes":
Each insertion was individually reasonable, since these are foundational
vocabulary that applies everywhere. The changes were cumulative: each later
insertion pushed the earlier one down, stacking all three ahead of "Discovery,
Governance, and Negotiation", which is the actual entry point for a first-time
reader.
Worth noting that #572, the earliest of these four primitives, placed Policies
after "Standard Capabilities". This PR follows that precedent and moves the
other three to join it, so all four core primitives sit together:
This is a pure reorder. No prose edits, no heading level changes. Verified
by comparing the sorted line multiset against the parent commit: identical,
same 3747 total lines. All 142 heading anchors are preserved, so the 20+ pages
that deep-link into
#quantities-and-units,#request-constraintsand#actionsare unaffected.Reviewing with
git diff --color-movedor ignoring whitespace makes the movemuch easier to read than the raw 2542/2542 diff.
Category (Required)
Related Issues
Checklist
!for breaking changes).Screenshots / Logs (if applicable)
Before (current
main),/specification/overview/:/ After (this PR):
Note: this PR fixes
/draft/. The/latest/alias resolves to the2026-08-25release, so restoring the live/latest/URL additionallyrequires backporting this commit to
release/2026-08-25— will send via a future PR.