Skip to content

docs(readme): consolidate conformance, surface subtle correctness wins#22

Merged
chad-loder merged 1 commit into
mainfrom
docs/readme-consolidate
May 13, 2026
Merged

docs(readme): consolidate conformance, surface subtle correctness wins#22
chad-loder merged 1 commit into
mainfrom
docs/readme-consolidate

Conversation

@chad-loder
Copy link
Copy Markdown
Owner

Summary

Restructures the README so the conformance story is the first H2 after the hero code, replacing the older "WHATWG conformance" + "Test corpus matrix" + "API surface" split which fragmented the same story across three sections.

Depends on #21 — the new conformance table claims 469 / 469 + the in-repo 130 unit tests = 599. That's only true once URLPattern.generate() lands. Either merge #21 first, or merge this and #21 together.

What changes

New ## Conformance section (right after the hero code)

New ### What we get right that's easy to miss subsection

Promotes the per-component canonicalisation rules that distinguish a spec-strict implementation from a stdlib approximation:

  • WHATWG URL parsing end-to-end via yarl (not urllib.parse)
  • IDNA2008 / UTS46 hostname canonicalisation via the third-party idna package (not Python's stdlib IDNA2003 codec)
  • Strict port parsing — "8080xyz" rejected
  • Case-preserving %XX in pattern literals (WPT 146 / 148)
  • U+FFFD substitution for unpaired surrogates (WPT 157)
  • Hostname truncation at ? / # / / / \

Consolidations

  • Dropped the duplicate "three places stricter than yarl" list from the How this differs from yarl section in favour of a one-line pointer to the new Conformance section + SPEC_DEVIATIONS.md.
  • Folded the API-surface table into a single sentence — the table was redundant alongside the WPT-suites table since every row was green.
  • Tightened the Install and BYO-regex-engine sections so the 99.5% / 100% framing lives in exactly one place (the Conformance section's stdlib-only callout).

Test plan

  • just lint — all tools green (ruff, mypy, pyright, ty, semgrep, shellcheck, rumdl, codespell, interrogate, validate-pyproject)
  • Headings outline reads cleanly: Hero → Conformance → aiohttp comparison → yarl comparison → Install → BYO regex engine → Quick start → Architecture
  • Hatch's PyPI-substitution rules in pyproject.toml rewrite the new relative links (docs/wpt-compliance.md, SPEC_DEVIATIONS.md, scripts/fetch_references.sh) to absolute GitHub URLs at sdist build time
  • Signed commit (ED25519)

No behavior changes; README-only.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 13, 2026
…ness wins

Restructures the README so conformance is the first H2 after the hero
code, replacing the older "WHATWG conformance" + "Test corpus matrix" +
"API surface" split which fragmented the same story across three
sections.

The new ``## Conformance`` section opens with the 469 / 469 headline,
shows a single seven-row table covering all five upstream WPT suites
plus the in-repo unit-test suite (599 tests total), and links out to:

  - docs/wpt-compliance.md — the auto-regenerated per-case report
  - SPEC_DEVIATIONS.md — documented deviations and stricter-than-yarl
    rules

A new ``### What we get right that's easy to miss`` subsection promotes
the per-component canonicalisation rules that distinguish a spec-strict
implementation from a stdlib approximation:

  - WHATWG URL parsing end-to-end via yarl (not urllib.parse)
  - IDNA2008 / UTS46 hostname canonicalisation via the third-party
    `idna` package (not Python's stdlib IDNA2003 codec)
  - Strict port parsing — "8080xyz" rejected
  - Case-preserving %XX in pattern literals (WPT 146 / 148)
  - U+FFFD substitution for unpaired surrogates (WPT 157)
  - Hostname truncation at ? / # / / / \

Drops the duplicate "three places stricter than yarl" list from the
``How this differs from yarl`` section in favour of a one-line pointer
to the Conformance section + SPEC_DEVIATIONS.md.

Folds the API-surface table into a single sentence — the table was
redundant alongside the WPT-suites table since every row was green.

Tightens the Install and BYO-regex-engine sections so the 99.5% /
100% framing lives in exactly one place (the Conformance section's
stdlib-only callout).

No behavior changes; README-only.
@chad-loder chad-loder force-pushed the docs/readme-consolidate branch from e149a9c to 5c55782 Compare May 13, 2026 03:32
@chad-loder chad-loder merged commit 242c32d into main May 13, 2026
11 checks passed
@chad-loder chad-loder deleted the docs/readme-consolidate branch May 13, 2026 03:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant