Contributing

physics-lint welcomes external contributions: new rules, additional case studies, documentation improvements, and CI integrations.

Development install

git clone https://github.com/tyy0811/physics-lint.git
cd physics-lint
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

The repository uses pre-commit for ruff + codespell:

pre-commit install

The pre-commit hook runs inside the activated venv; python may be shadowed by a shell function in some environments, so prefer .venv/bin/python directly when troubleshooting.

Running tests

.venv/bin/pytest --import-mode=importlib -v

Running the linter on this repo (dogfooding)

.venv/bin/python -m physics_lint check tests/fixtures/good_adapter.py --format text

The dogfood corpus is at dogfood/laplace_uq_bench/; six trained surrogates plus baselines exercise the rule set.

Adding a new rule

A new rule requires three artifacts:

  1. Rule implementation at src/physics_lint/rules/ph_<cat>_<nnn>.py, following the registry pattern. Read existing rules for examples — PH-SYM-001 (continuous symmetry) and PH-CON-001 (mass conservation) are good starting points.

  2. External-validation directory at external_validation/PH-<CAT>-<NNN>/ containing:

    • README.md with a mandatory ## Rule reference section (user-facing) and a separate F1/F2/F3-style validation stack below it. The docs build fails loudly if the canonical section is missing.

    • CITATION.md with the function-labeled citation stack (F1 mathematical legitimacy, F2 correctness fixture, F3 real-world anchor).

    • One or more test_*.py files exercising the rule on calibrated fixtures.

  3. Harness fixture at external_validation/_harness/ if the rule needs a new field type or analytical solution; otherwise the existing harness covers it.

Adding a case study

Case studies live under external_validation/_rollout_anchors/. Each case study has its own subdirectory with a README.md whose canonical heading is ## Case study reference. The docs build emits a page from the canonical section.

Pull requests

  • Open against master.

  • Pre-commit hooks must pass.

  • Test suite must pass.

  • New rules require the documentation contract above (canonical section + citation stack + fixtures).

  • Squash merging is the default.

Codex review

Every major change (new rule, new case study, new public surface) benefits from a Codex adversarial-review pass before merge. Maintainers run this; contributors can request a Codex review on a PR by tagging the issue.