From 3e8c8e4b3b7c1ea612d0eb3c994328d5a6804ed1 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 19:45:50 +0100 Subject: [PATCH] policy(docs): README must be Markdown (not AsciiDoc) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README renders in GitHub community-health, the GitHub profile (profile READMEs render only README.md), and external MCP directories (Glama) — all show AsciiDoc as raw markup. So README joins the GitHub-required-.md set; README.md is canonical and a README.adoc alongside it is a duplicate to remove. Replaces the earlier .adoc-primary-with-Glama-carve-out rule for README. doc-format.yml: README out of the .adoc-primary duplicate loop; README.md+README.adoc -> hard error (keep .md); lone README.adoc -> warning (migration nudge). Estate README.adoc->.md conversion sweep follows. Co-Authored-By: Claude Opus 4.8 --- .claude/CLAUDE.md | 5 +++-- .github/workflows/doc-format.yml | 38 +++++++++++++++++--------------- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index bec9e401..6e6e0167 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -167,8 +167,9 @@ Both are FOSS with independent governance (no Big Tech). ### Documentation Format - All docs must be `.adoc` (AsciiDoc) except GitHub-required files -- GitHub-required `.md`: SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md -- No duplicate formats (if `.adoc` exists, don't also have `.md`) +- GitHub-required `.md` (must be Markdown): **README.md**, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md +- **README must be `.md`, not `.adoc`.** README renders in GitHub community-health, the GitHub profile page (profile READMEs *only* render `README.md`), and external MCP directories (Glama) — all of which show AsciiDoc as raw markup. Keep `README.md`; do not keep a `README.adoc` alongside it. (This replaces the earlier `.adoc`-primary-with-Glama-carve-out rule for README.) +- No duplicate formats for the `.adoc`-primary docs (if `ARCHITECTURE.adoc` etc. exists, don't also have `.md`) ### Security Requirements diff --git a/.github/workflows/doc-format.yml b/.github/workflows/doc-format.yml index 8aa937f4..b35b518a 100644 --- a/.github/workflows/doc-format.yml +++ b/.github/workflows/doc-format.yml @@ -31,23 +31,23 @@ jobs: run: | DUPLICATES=0 - # Check for docs that exist in both .md and .adoc (except GitHub-required) - for doc in README ARCHITECTURE ROADMAP PHILOSOPHY INSTALL CHANGELOG; do + # .adoc-primary docs: keep only .adoc. README is NOT here — README is a + # GitHub-required Markdown file (see the README rule below). + for doc in ARCHITECTURE ROADMAP PHILOSOPHY INSTALL; do if [ -f "${doc}.md" ] && [ -f "${doc}.adoc" ]; then - # Glama carve-out: the Glama MCP-server directory (glama.ai) requires a - # README.md to index a server and will NOT render README.adoc. When a - # glama.json is present, README.md is permitted alongside the canonical - # README.adoc. README.adoc remains the source of truth. This is a Glama - # limitation, not an owner-policy change. See contractiles/CANONICAL-TEMPLATES.adoc. - if [ "${doc}" = "README" ] && [ -f "glama.json" ]; then - echo "::notice::README.md kept alongside README.adoc (Glama carve-out: glama.json present; .adoc remains canonical)." - continue - fi echo "::error::Duplicate documentation: ${doc}.md and ${doc}.adoc both exist. Keep only .adoc" DUPLICATES=$((DUPLICATES + 1)) fi done + # README MUST be Markdown: it renders in GitHub community-health, the GitHub + # profile, and external MCP directories (Glama) — all of which show AsciiDoc + # as raw markup. So README.md is canonical; README.adoc is a duplicate to remove. + if [ -f "README.md" ] && [ -f "README.adoc" ]; then + echo "::error::Duplicate README: keep README.md (required Markdown); remove README.adoc." + DUPLICATES=$((DUPLICATES + 1)) + fi + # CONTRIBUTING can have both but .md should just be a redirect if [ -f "CONTRIBUTING.md" ] && [ -f "CONTRIBUTING.adoc" ]; then if ! grep -q "See.*CONTRIBUTING.adoc" CONTRIBUTING.md 2>/dev/null; then @@ -62,14 +62,16 @@ jobs: echo "✓ No duplicate documentation formats found" - - name: Check documentation uses .adoc + - name: Check documentation format run: | - # List of files that MUST be .md for GitHub community health - # SECURITY.md, CONTRIBUTING.md (can redirect), CODE_OF_CONDUCT.md, CHANGELOG.md - - # Check README is .adoc (not .md) - if [ -f "README.md" ] && [ ! -f "README.adoc" ]; then - echo "::warning::README.md found without README.adoc. Consider converting to AsciiDoc." + # Files that MUST be .md for GitHub community-health / profile / Glama: + # README.md, SECURITY.md, CONTRIBUTING.md (can redirect), CODE_OF_CONDUCT.md, CHANGELOG.md + + # README must be Markdown. A lone README.adoc renders as raw markup in + # community-health/profile/Glama — nudge to convert (warning during the + # estate-wide migration; the duplicate case above is the hard error). + if [ -f "README.adoc" ] && [ ! -f "README.md" ]; then + echo "::warning::README.adoc without README.md — README must be Markdown (renders raw as AsciiDoc in community-health/profile/Glama). Convert to README.md." fi # Check other docs are .adoc