From 61d1ebe038d3572a3237136dddf451cd5eb5a2a4 Mon Sep 17 00:00:00 2001 From: Heewon Oh Date: Tue, 3 Nov 2026 01:33:08 +0900 Subject: [PATCH] docs: document the contributor workflow that CI enforces Adds a README "Development" section with a fenced bash block: pip install -e ".[test]", python -m pytest -m "not slow", and python scripts/check_docs.py, plus the system tools CI installs (ffmpeg, libsndfile1, libchromaprint-tools for fpcalc). check_docs.py extracts the block (README.md:226-227); injecting a bogus flag into the check_docs command makes it report "`scripts/check_docs.py` does not accept --bogus", so the block is verified. Assumptions: - The section sits just before License, after the protocol docs, because it is for contributors, not benchmark users. - pytest is on check_docs' ignore list (third-party), so only the check_docs command's flags are machine-verified; --skip-flags is shown in prose and exists in its parser. --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 7b2a1f9..bf06f2d 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,27 @@ ArtifactNet's non-finite chunk investigation is reproducible with at least four finite scores among seven fixed chunks; the strict any-non-finite result remains a separate sensitivity analysis. +## Development + +CI (`.github/workflows/ci.yml`) runs the fast suite and the documentation check on +every push to `main` and every pull request, on CPU with Python 3.12. To run the +same checks locally: + +```bash +# System tools: ffmpeg, libsndfile, and fpcalc (Chromaprint), e.g. on Ubuntu: +# apt-get install ffmpeg libsndfile1 libchromaprint-tools +pip install -e ".[test]" +python -m pytest -m "not slow" +python scripts/check_docs.py +``` + +Tests marked `slow` need network access, model weights, or inference, and are +not run in CI; run them with `python -m pytest -m slow`. `check_docs.py` checks +that every relative link in `README.md`, `NOTICE.md`, `docs/*.md` and +`paper/README.md` resolves, and that every `--flag` in a documented +`python -m ...` or `python scripts/....py` command is accepted by that program. +Use `python scripts/check_docs.py --skip-flags` to check links only. + ## License The runner code is MIT licensed. **Model weights and datasets are subject to