Repository navigation
docs(adjudication): decide how anchors and transclusions resolve - #41
Merged
Merged
Conversation
Add SPEC.md: the CommonMark 0.31.2 block-level profile with GFM pipe tables, frontmatter, blocks and leaves, region markers and what each binds, name resolution and heading slugs, and the eleven refusals with the identifiers the conformance suite compares, including the two fixed orders between them. The document adds no decision. It defers to the adjudications where they disagree, and lists in its last section each question they leave open, naming the suite reading that pins it where one does. Point README.md, AGENTS.md and the case tree's README at it. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Add adjudication 0003. Comment and suggestion records live one per file in <doc>.notes/. An anchor resolves from two snapshots, its base blob and the current text, through leaf correspondence, near-copy, refill, crowded-gap and twin rules, a 32-code-point context and a character alignment, and is loud wherever those disagree. Comments follow moves; only open suggestions apply, never on a moved leaf, and only through an exact offset mapping. A transclusion is a paragraph that is one link titled "transclude", pinned by the referrer and refused once the name is rebound, which amends 0001. The document names the four edit shapes the bytes cannot tell from legitimate edits, and what a tool may add on top of the format. Add SPEC.md section 11 with the rules and the resolution reasons, move "not decided" to section 12 with what 0003 leaves open, and point the README, AGENTS.md and the brief at it. No implementation and no cases. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Limit "only refuses more" to merge parents and document identity, and describe re-basing before landing as what it is, with a CI check that reports records that do not resolve instead of failing the landing. Define write-back through the parse, so only the span's own text must match after NFC. Refuse a short context away from the leaf's edge and an empty span as record-inconsistent, write replace as stored, and use not-in-profile for any snapshot the profile refuses. List the details 0003 fixes beyond its thirteen answers, add #REF!(name) to the reasons, and note that an insertion between a one-line marker and its leaf rebinds the name. Correct citations: 0002 §4 gives no syntax, the author-chosen name comes from D8 §7.2 and §11, the thresholds are borrowed from difflib ratios, and wrong_on_deleted counts wrong units. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Scope the ambiguous-table order to one table's lines, and the marker indentation rule to where a block can start, marking each as a reading of the addendum's wording. State that U+0000 becomes U+FFFD per the pinned grammar, that UTF-8 is the brief's decision with no refusal code yet, that a lazy delimiter line is paragraph text, and that 0002's Decision text decides the general table rule. List conflict markers inside a fence as reading 4 beside reading 12, add the transclusion unit from 0002's Decision, and leave whether a slug names a heading or its section undecided, as 0002 §4 does. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
The tree is already exempt from normalisation by .gitattributes. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Write each line break in a suggestion's replacement with the line's own ending, say that a bare CR is the source of a content \n in a bare-CR file, and point 0003's write-back bullet at the content-based mapping in section 11.7. A lazy line that starts another block, such as `- | -`, starts it; only other lazy lines are paragraph text. Call a top-level indented marker in paragraph context a paragraph continuation line. Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@users.noreply.github.com>
Signed-off-by: Cameron Brooks <95648474+CameronBrooks11@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.
Adds
docs/adjudications/0003-anchors.md, which decides how comments, suggestions and transclusions anchor to text in a blockspec document. The aim is that after edits and a stockgit merge, an anchor either lands on the right text or is refused loudly. It also addsSPEC.md§11, which carries the resulting rules.Stacked on #40, whose
SPEC.mdthis extends. The base isdocs/spec-draft-0, so the diff shows only this change.No implementation and no conformance cases. The reference resolver and the cases come later, and the cases come first, from an author who has not read a resolver.
What 0003 decides
<doc>.notes/MOVED; suggestions never apply to onebaseisREFUSED(base-unavailable). Before landing, a tool MAY re-base each record that resolves onto the branch head. A CI check MAY require that; records that do not resolve keep theirbase, are reported, and do not fail the landing[t](doc.md#name "transclude"), amending 0001#REF!(reply-to)status: opensuggestions applyunmappable-offset0003 also fixes these details beyond the thirteen answers, and lists them under its decision table:
not-in-profilefor any snapshot the profile refuses, and#REF!(name);record-inconsistentfor a short context away from the leaf's edge, for an emptyspan, and for a pinned name that binds nothing;replaceis written exactly as stored, never normalised.It also covers:
spike/LOG.md§9 is cited as the published single-commit instance of that family.No figure in 0003 measures these rules on real history. Its What would reverse it starts with that replay.
Outline
0003:
Then the effect on 0001 and 0002, and what draft 0 carries.
SPEC.md§11 has twelve subsections:The former §11, Not decided, is now §12.
Also edited:
SPEC.md§4.2 names the one inline shape with meaning, and §8.3 says slugs are not transclusion targetsREADME.mdandAGENTS.mdlist 0003 and say it has no cases yetDESIGN-BRIEF.md§2 points its quote-anchoring question at 0003Open questions 0003 leaves undecided
These are listed in
SPEC.md§12:reply-tositsleaf.text, since §6.3 gives a table's content as rows of cellsEXACTagainstMOVEDpathresolves, a destination with no path, the title's other quoting forms, atranscludelink among other text, a transclusion inside a container, a transclusion with no pin, and self-transclusionChecks
The case tree and the reference reader are unchanged. Nothing implements 0003 yet.