Contributing and verification

Change one owned behavior, preserve its statistical contract and retain the evidence needed for review.

Start from the current checkout

git clone https://github.com/zzhang0123/bayesmith.git
cd bayesmith
uv venv --python 3.12
uv pip install -e . --group dev

Read the status line of any design document you cite: a page under docs/ says whether it is the normative design, a current module specification or a dated record.

Separate a product defect from a platform-dependent numerical premise. Prefer independent analytic oracles, exact constructions and consequences over tests that merely search source spelling.

Run the appropriate layer

.venv/bin/python -m pytest -n 4 -m "not full"
# Full layer, which adds the numerical-gate boundary and mutation grids:
.venv/bin/python -m pytest -n 4
.venv/bin/ruff check --no-cache src/ tests/

Do not add another -q; pytest configuration already supplies one. Save the log, JUnit XML and exit code in one run directory. Only exit 1 means failed assertions; interrupted, internal-error, usage-error and killed runs require different interpretations.

For numerical fixture repairs, do not widen a tolerance just to pass. Establish which property is required and demonstrate that meaningful mutations still fail.

Build and verify the documentation

python3 tools/build_docs.py
python3 tools/build_docs.py --check
node tools/check_docs_math.cjs

The builder uses only Python's standard library. It checks source exports, links, anchors and stale generated output. The Node check renders every inventoried formula using the vendored KaTeX engine. Content lives under site/content/, navigation in site/navigation.json, examples in site/snippets/. API pages are generated from source signatures and docstrings without importing the package.

Build success does not execute numerical examples or establish browser accessibility. Run downloadable tutorials in a suitable environment, then inspect navigation, search, focus, theme and small-screen overflow separately.

Review by independent responsibility

Architecture review checks dependencies and ownership. Numerical review checks estimands, support, normalization and failure behavior. API review checks shapes, compatibility and provenance. Packaging review checks the installed artifact and shipped resources. Documentation review follows a real reader from installation to interpretation. Resolve findings, rerun affected checks and have the revised result reviewed again.