Skip to content

ASCII-only rule: 52 docs in breach, ~3,700 characters, invisible because the test never ran #1331

Description

@PipFoweraker

tests/test_ascii_compliance.py fails on 52 documentation files. The test is
correct; the docs are in breach. It has been invisible because nothing has ever
run the Python test suite
-- no workflow invoked pytest, and pytest was not even
in requirements-dev.txt (both fixed alongside this issue).

What it is

The ASCII-only rule is a hard rule (#744, restated in CLAUDE.md): no non-ASCII in
.py/.md/.json/.yaml/.txt/.cfg/.sh. enforce-standards runs --incremental in
pre-commit -- only over the files a commit touches -- so the untouched tree drifted
and nothing measured the total. This is the same accumulation shape already
recorded for black/isort/ruff in tools/check_guard_parity.py.

Measured on main at the time of filing:

$ grep -rhoP '[^\x00-\x7F]' --include="*.md" docs/ *.md | sort | uniq -c | sort -rn | head
   1340  --  (em dash)
   1056  box-drawing horizontal
    526  right arrow
    154  box-drawing vertical
    123  middle dot
     94  section sign
     87  multiplication sign
     82  en dash
     50  box-drawing tee
     41  almost-equal

~3,700 characters. 158 files outside godot/ contain non-ASCII across all the
rule's extensions; the test's own scope (root *.md + docs/**/*.md) accounts for
the 52 failures.

Why this is not a five-minute sed

About 1,056 of them are box-drawing characters inside ASCII diagrams. A blind
transliteration would mangle every diagram it touches. scripts/intelligent_ascii_converter.py
exists and is report-only by default (--apply to write, per #773/PR #849), but
CLAUDE.md records that a careless run of exactly this tool once sprayed
transliterated churn across the tree. The em-dashes, arrows and quotes are
mechanical; the diagrams need a human eye.

Suggested order:

  1. The mechanical classes first (em/en dash --, arrows ->, ellipsis ...,
    smart quotes) in their own reviewable commit.
  2. The box-drawing diagrams second, redrawn in the house ASCII style
    (+--, |, `), one file at a time.
  3. Then re-include the test and delete the --ignore below.

The exclusion to remove when this lands

.github/workflows/enhanced-cicd-pipeline.yml, "Run Test Suite":

python -m pytest tests/ -q --ignore=tests/test_ascii_compliance.py

The step prints why the file is excluded, so the debt is stated on every run
rather than hidden. Removing the --ignore is the definition of done here.

Context

Found while wiring the Python suite into CI for the first time. In the same pass,
67 pygame-era test files were deleted (each byte-identical to a copy already in
archive/legacy-pygame/tests/), which is the decision #1117 has been waiting on
since 2026-08-04. Two of those 67 did not fail loudly -- they caught the
ImportError, printed, and return Falsed, so pytest counted them as 13
passing tests
that asserted nothing about a module that does not exist.

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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions