Skip to content

chore: rename docs/specs/SPEC.md and faces.md to .adoc #96

Description

@hyperpolymath

Background

The estate documentation-format rule (DOC-FORMAT in .claude/CLAUDE.md) is:

All documentation files in docs/ must use .adoc extension.
Exception: GitHub community-health files must use .md by 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.mddocs/specs/SPEC.adoc
  • docs/specs/faces.mddocs/specs/faces.adoc

What "rename" means here

For each file:

  1. git mv docs/specs/<name>.md docs/specs/<name>.adoc
  2. 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
  3. Add the standard preamble at top:
    // SPDX-License-Identifier: PMPL-1.0-or-later
    = <Title>
    :toc: macro
    :toclevels: 2
    :source-highlighter: rouge
    
    toc::[]
    
  4. Grep the rest of the repo for inbound references to the old .md paths and update each one (e.g. docs/specs/SPEC.md referenced from other specs, READMEs, justfiles, CI scripts, the bin/main.ml --help blurb 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.md and faces.md show 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 against main.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions