diff --git a/Makefile b/Makefile index ab63b30d..53167a6f 100644 --- a/Makefile +++ b/Makefile @@ -20,7 +20,7 @@ help: ' make check-browser run browser smokes (set CHROMIUM=/path/to/chrome)' \ ' make check-conformance run accessibility + Chromium/Firefox/WebKit conformance' \ ' make check-docs run docs examples and public claim guardrails' \ - ' make check-examples run README/API examples and Reflex asset registry checks' \ + ' make check-examples run canonical API examples and Reflex asset registry checks' \ ' make check-security run standalone HTML safety and client text-sink checks' \ ' make check-errors run public error, LOD, and mutation-safety tests' \ ' make check-api run lazy public API and type-surface checks' \ diff --git a/scripts/check_claim_guardrails.py b/scripts/check_claim_guardrails.py index cb5f1a07..47a133e2 100644 --- a/scripts/check_claim_guardrails.py +++ b/scripts/check_claim_guardrails.py @@ -18,7 +18,6 @@ ROOT = Path(__file__).resolve().parents[1] DEFAULT_DOCS = ( "pyproject.toml", - "README.md", "SECURITY.md", "CONTRIBUTING.md", "spec/api/api-examples.md", @@ -26,8 +25,6 @@ "spec/api/chart-roadmap.md", "spec/process/contributing.md", "spec/process/production-readiness.md", - "examples/reflex/README.md", - "examples/fastapi/README.md", ) BROAD_SUPERLATIVE_RE = re.compile( diff --git a/scripts/check_python_floor.py b/scripts/check_python_floor.py index 0f7e45c8..4be7e1d3 100644 --- a/scripts/check_python_floor.py +++ b/scripts/check_python_floor.py @@ -41,10 +41,7 @@ "node_modules", } -DECLARATION_DOCS = ( - Path("README.md"), - Path("spec/process/production-readiness.md"), -) +DECLARATION_DOCS = (Path("spec/process/production-readiness.md"),) def iter_python_files(paths: Iterable[Path]) -> list[Path]: diff --git a/scripts/verify_sdist.py b/scripts/verify_sdist.py index daa872f2..3fedfd44 100644 --- a/scripts/verify_sdist.py +++ b/scripts/verify_sdist.py @@ -34,10 +34,8 @@ "LICENSE", "Makefile", "PKG-INFO", - "README.md", "SECURITY.md", "benchmarks/__init__.py", - "benchmarks/README.md", "benchmarks/_browser.py", "benchmarks/_xy_browser.py", "benchmarks/baseline.json", @@ -54,7 +52,6 @@ "benchmarks/bench_workflows.py", "benchmarks/categories.py", "benchmarks/environment.py", - "spec/README.md", "spec/design-dossier.md", "spec/api/api-examples.md", "spec/api/chart-roadmap.md", @@ -97,12 +94,10 @@ "python/xy/static/index.js", "python/xy/static/standalone.js", "python/xy/widget.py", - "examples/fastapi/README.md", "examples/fastapi/pyproject.toml", "examples/fastapi/app.py", "examples/fastapi/charts.py", "examples/fastapi/live_drilldown.py", - "examples/reflex/README.md", "examples/reflex/pyproject.toml", "examples/reflex/rxconfig.py", "examples/reflex/xy_reflex_demo/__init__.py", @@ -408,18 +403,6 @@ def verify_sdist(path: str) -> None: "Performance Claims", }, ) - _require_file_contains( - path, - root, - "examples/reflex/README.md", - {"reflex-xy showcase", "reflex run", "reflex_xy.XYPlugin()"}, - ) - _require_file_contains( - path, - root, - "examples/fastapi/README.md", - {"FastAPI", "chart.to_html()", "/api/xy/drilldown"}, - ) _require_file_contains( path, root, diff --git a/spec/benchmarks/results.md b/spec/benchmarks/results.md index 20112565..6b04b3b7 100644 --- a/spec/benchmarks/results.md +++ b/spec/benchmarks/results.md @@ -188,9 +188,9 @@ environment metadata and benchmark category IDs. ## Copyable claim taxonomy -Use these shapes when turning benchmark rows into README text, release notes, or -posts. The goal is to make every public claim reproducible from a row in this -document or from a verified JSON artifact. +Use these shapes when turning benchmark rows into public prose, release notes, +or posts. The goal is to make every public claim reproducible from a row in +this document or from a verified JSON artifact. | Claim shape | Safe wording pattern | Required context | |---|---|---| diff --git a/spec/process/contributing.md b/spec/process/contributing.md index c1f88f1f..f47df8cb 100644 --- a/spec/process/contributing.md +++ b/spec/process/contributing.md @@ -43,7 +43,7 @@ toolchain with `cargo`, `rustc`, and clippy for native-core checks. If clippy is missing, run `rustup component add clippy`. If you are only touching docs or pure Python shell code, `make check` is the fast non-JS/non-Rust gate. -When README/API prose changes, run the focused docs gate: +When canonical API prose or examples change, run the focused docs gate: ```bash make check-docs @@ -96,15 +96,15 @@ regression comparison scripts, or report-schema validation, run: make check-benchmark-harness ``` -When you edit public docs, README text, package metadata, benchmark summaries, -or anything that could become a public performance claim, run: +When you edit public docs, package metadata, benchmark summaries, or anything +that could become a public performance claim, run: ```bash make check-claims ``` -When you edit README snippets, `spec/api/api-examples.md`, or the Reflex example -dashboard registry/assets, run: +When you edit `spec/api/api-examples.md` or the Reflex example dashboard +registry/assets, run: ```bash make check-examples @@ -235,7 +235,7 @@ the `` placeholder, name it explicitly, for example the patch; run `make check-security` for export/client text-sink changes. - Benchmarks label mode truthfully: `direct`, `decimated`, `density`, `sampled`, or `adaptive`. -- README/docs examples still match the current public API. +- Canonical API examples still match the current public API. - New public exports appear in `xy.__all__`, lazy `_EXPORTS`, and tests; run `make check-api` after public export or annotation changes. - Lazy import boundaries still keep package import light; run diff --git a/spec/process/production-readiness.md b/spec/process/production-readiness.md index ab058709..8b921be2 100644 --- a/spec/process/production-readiness.md +++ b/spec/process/production-readiness.md @@ -143,8 +143,8 @@ production-facing push: | Changed surface | Focused gate | |---|---| -| README/API prose, examples, public benchmark wording | `make check-docs` | -| README snippets, `spec/api/api-examples.md`, Reflex chart registry/assets | `make check-examples` | +| API prose, examples, public benchmark wording | `make check-docs` | +| `spec/api/api-examples.md`, Reflex chart registry/assets | `make check-examples` | | Public validation, error messages, builder rollback, LOD/drill mutation boundaries, chart/widget caching | `make check-errors` | | Public exports, lazy import mappings, component factories, public annotations | `make check-api` | | Import-time budget, `xy.__init__`, dependency boundaries, widget/export/backend import boundaries | `make check-import` | @@ -166,8 +166,7 @@ Use this before pushing production-facing changes: make check-full ``` -Use this after editing README/API docs, example snippets, or public benchmark -wording: +Use this after editing API docs, example snippets, or public benchmark wording: ```bash make check-docs @@ -224,8 +223,8 @@ verify those exact files rather than rebuilding locally: make check-artifacts SDIST=/path/to/xy.tar.gz WHEEL=/path/to/xy.whl ``` -Use this after editing README snippets, `spec/api/api-examples.md`, or the Reflex -dashboard chart registry/assets: +Use this after editing `spec/api/api-examples.md` or the Reflex dashboard chart +registry/assets: ```bash make check-examples @@ -275,8 +274,8 @@ tests: make check-benchmark-harness ``` -Use this after editing public docs, README text, package metadata, benchmark -summaries, release notes, or other performance-claim surfaces: +Use this after editing public docs, package metadata, benchmark summaries, +release notes, or other performance-claim surfaces: ```bash make check-claims @@ -371,7 +370,7 @@ Before tagging a release: package-only: docs, tests, benchmarks, scripts, and the `examples/` apps are sdist-only. - Confirm the wheel size budget is still below 15 MB. -- Confirm README examples and `spec/api/api-examples.md` run against the tagged API. +- Confirm `spec/api/api-examples.md` runs against the tagged API. - Confirm package metadata uses measured, scoped language rather than broad "faster/best" positioning. - Confirm performance claims mention chart type, mode, backend, data size, and diff --git a/tests/test_python_floor.py b/tests/test_python_floor.py index 08ea4d11..75e9cd0a 100644 --- a/tests/test_python_floor.py +++ b/tests/test_python_floor.py @@ -23,7 +23,6 @@ def _write_floor_repo( *, requires_python: str = ">=3.11", ruff_target: str = "py311", - readme: str = "Install with Python 3.11+.\n", production_readiness: str = "The current contract is Python 3.11+ only.\n", ) -> None: root.joinpath("spec", "process").mkdir(parents=True) @@ -35,7 +34,6 @@ def _write_floor_repo( f'target-version = "{ruff_target}"\n', encoding="utf-8", ) - root.joinpath("README.md").write_text(readme, encoding="utf-8") root.joinpath("spec", "process", "production-readiness.md").write_text( production_readiness, encoding="utf-8", @@ -65,11 +63,11 @@ def test_python_floor_rejects_mismatched_ruff_target(tmp_path: Path) -> None: def test_python_floor_rejects_missing_docs_floor(tmp_path: Path) -> None: - _write_floor_repo(tmp_path, readme="Install with Python.\n") + _write_floor_repo(tmp_path, production_readiness="The current contract is Python only.\n") errors = check_python_floor.check_declared_floor(tmp_path) - assert any("README.md" in error and "Python 3.11+" in error for error in errors) + assert any("production-readiness.md" in error and "Python 3.11+" in error for error in errors) def test_python_floor_accepts_annotated_file_with_future_annotations(tmp_path: Path) -> None: diff --git a/tests/test_verify_sdist.py b/tests/test_verify_sdist.py index 32ebcef8..c8fd9d46 100644 --- a/tests/test_verify_sdist.py +++ b/tests/test_verify_sdist.py @@ -27,7 +27,6 @@ "const padding = '" + ("x" * 1000) + "';\n" "export default { render, decodeFrame };\n" ) -README_MD = "# XY\n" + ("README fixture\n" * 100) API_EXAMPLES_MD = ( "# API Examples\n\n" "## Chart Family Quick Reference\n\n" @@ -59,21 +58,11 @@ "## Pull Request Checklist\n\n" "Run make check-full, make check-sdist, make check-wheel, and " "make check-benchmark-report.\n" - "Run make check-examples for README snippets, spec/api/api-examples.md, and " + "Run make check-examples for spec/api/api-examples.md and " "the example apps.\n\n" "## Performance Claims\n\n" "Claims need benchmark context.\n" + ("contributing padding\n" * 100) ) -REFLEX_README_MD = ( - "# reflex-xy showcase\n\n" - "Wired with reflex_xy.XYPlugin() in rxconfig.py; run with reflex run.\n" - + ("reflex readme padding\n" * 100) -) -FASTAPI_README_MD = ( - "# xy FastAPI example\n\n" - "A FastAPI app that generates charts with chart.to_html() and serves a " - "live drilldown via POST /api/xy/drilldown.\n" + ("fastapi readme padding\n" * 100) -) CI_YML = ( "name: CI\n" "jobs:\n" @@ -168,8 +157,6 @@ def _write_sdist( data = STANDALONE_JS.encode("utf-8") elif name == "js/src/60_entries.ts": data = ENTRIES_JS.encode("utf-8") - elif name == "README.md": - data = README_MD.encode("utf-8") elif name == "spec/api/api-examples.md": data = API_EXAMPLES_MD.encode("utf-8") elif name == "spec/benchmarks/results.md": @@ -178,10 +165,6 @@ def _write_sdist( data = PRODUCTION_READINESS_MD.encode("utf-8") elif name == "spec/process/contributing.md": data = CONTRIBUTING_MD.encode("utf-8") - elif name == "examples/reflex/README.md": - data = REFLEX_README_MD.encode("utf-8") - elif name == "examples/fastapi/README.md": - data = FASTAPI_README_MD.encode("utf-8") elif name == ".github/workflows/ci.yml": data = CI_YML.encode("utf-8") elif name == ".github/workflows/codspeed.yml": @@ -426,28 +409,6 @@ def test_verify_sdist_rejects_stale_contributing_doc(tmp_path: Path) -> None: verify_sdist.verify_sdist(str(sdist)) -def test_verify_sdist_rejects_stale_reflex_example_readme(tmp_path: Path) -> None: - sdist = tmp_path / "xy-0.0.1.tar.gz" - _write_sdist( - sdist, - replacements={"examples/reflex/README.md": "# Reflex\n" + ("padding\n" * 200)}, - ) - - with pytest.raises(AssertionError, match="examples/reflex/README"): - verify_sdist.verify_sdist(str(sdist)) - - -def test_verify_sdist_rejects_stale_fastapi_example_readme(tmp_path: Path) -> None: - sdist = tmp_path / "xy-0.0.1.tar.gz" - _write_sdist( - sdist, - replacements={"examples/fastapi/README.md": "# FastAPI\n" + ("padding\n" * 200)}, - ) - - with pytest.raises(AssertionError, match="examples/fastapi/README"): - verify_sdist.verify_sdist(str(sdist)) - - def test_verify_sdist_rejects_missing_release_workflow(tmp_path: Path) -> None: sdist = tmp_path / "xy-0.0.1.tar.gz" _write_sdist(sdist, omit={".github/workflows/release.yml"}) @@ -521,7 +482,7 @@ def test_verify_sdist_rejects_generated_artifacts(tmp_path: Path, artifact: str) def test_verify_sdist_rejects_duplicate_file_member(tmp_path: Path) -> None: sdist = tmp_path / "xy-0.0.1.tar.gz" - _write_sdist(sdist, extra={"README.md": b"duplicate"}) + _write_sdist(sdist, extra={"LICENSE": b"duplicate"}) with pytest.raises(AssertionError, match="duplicate file member"): verify_sdist.verify_sdist(str(sdist))