Repository navigation
Closed
Labels
documentationDocs, prose, diagrams, READMEs, ADRsDocs, prose, diagrams, READMEs, ADRsgood first issueGood for newcomersGood for newcomers
Description
Background
The estate documentation-format rule (DOC-FORMAT in .claude/CLAUDE.md) is:
All documentation files in
docs/must use.adocextension.
Exception: GitHub community-health files must use.mdby name (CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,CHANGELOG.md,README.md).
Two files in docs/specs/ on main predate this rule and still use .md. Neither matches the community-health exception.
Files to rename
-
docs/specs/SPEC.md→docs/specs/SPEC.adoc -
docs/specs/faces.md→docs/specs/faces.adoc
What "rename" means here
For each file:
git mv docs/specs/<name>.md docs/specs/<name>.adoc- Convert Markdown syntax to AsciiDoc:
- Headings:
#/##/###/####→=/==/===/==== - Pipe-tables →
[cols="..."]|===blocks - Fenced code (```lang) →
[source,lang]`----` listings - Emphasis:
**bold**→*bold*,*italic*→_italic_ - Inline code (
`x`) stays the same
- Headings:
- Add the standard preamble at top:
// SPDX-License-Identifier: PMPL-1.0-or-later = <Title> :toc: macro :toclevels: 2 :source-highlighter: rouge toc::[] - Grep the rest of the repo for inbound references to the old
.mdpaths and update each one (e.g.docs/specs/SPEC.mdreferenced from other specs, READMEs, justfiles, CI scripts, thebin/main.ml --helpblurb if applicable).
Acceptance
- Both files renamed and rewritten in valid AsciiDoc.
git grep -nE 'docs/specs/(SPEC|faces)\.md'returns no hits except in CHANGELOG-style historical notes.- The PR body lists every inbound reference touched.
Why this is good-first-issue
The conversion is mechanical, the rule is documented in .claude/CLAUDE.md (DOC-FORMAT), and docs/specs/affex-spec.adoc (landed on PR #93's branch) is a worked example of the same Markdown → AsciiDoc conversion at this scale.
Out of scope
- Do not touch any open PR's branch as part of this work —
SPEC.mdandfaces.mdshow up in several open PRs' diffs and renaming them mid-PR creates merge churn. Wait for those PRs to merge or be closed, then do this rename in a single small PR againstmain.
Metadata
Metadata
Assignees
Labels
documentationDocs, prose, diagrams, READMEs, ADRsDocs, prose, diagrams, READMEs, ADRsgood first issueGood for newcomersGood for newcomers
Activity