Skip to content

Contributing

The bar

Two rules matter more than style:

  1. No claim may outrun what the code does. Every number in a README must be reproducible by running the published code. tools/check_readme_examples.py enforces this; a stale transcript fails CI.
  2. When in doubt, refuse. A new feature may not produce a confident-looking answer it has not earned. If an input is degenerate, exit 3 and say why.

A test is never weakened to make CI green. If a test fails, either the code is wrong or the test encoded a wrong contract — fix whichever it is, and say which.

Submitting a benchmark result

pip install git+https://github.com/nickharris808/pqc-mfb
pqc-mfb submit -o results.json     # all 322 case ids, seeded from the baseline
# flip the cases your implementation holds
pqc-mfb score results.json

Open an issue on pqc-mfb with the output. Low scores are welcome and interesting — a leaderboard of perfect scores would tell nobody anything. What is not welcome is a submission with unanswered cases presented as a pass; the scorer will call it INCOMPLETE.

Reporting a wrong number

The highest-value contribution. If a documented number does not reproduce, that is a defect in the class this project cares most about. Include the command, the output you got, and your platform.

Adding a test

Adversarial tests are the most welcome kind. The oracle is:

No input may produce a confident-looking answer that is wrong.

Confident-wrong is a P0. A crash is a P1. Ugly-but-honest is a P2.

If you add a test that cannot fail, it is worse than no test. Every verifier here has a companion job that plants a defect and requires the check to catch it — and asserts the suite is green before mutating, because a mutation test that runs against an already-red suite proves nothing.

Development

git clone https://github.com/nickharris808/<repo>
cd <repo>
pip install -e ".[dev]" && pytest

pqc-dos-embedded needs arm-none-eabi-gcc and qemu-system-arm; farkas-check any C99 compiler; pqc-dos-gate-rtl Yosys; pqc-bounds-lean elan; pqc-sizes-js Node ≥ 18. The rest are pure Python ≥ 3.9.

Lint with ruff check . — the config is committed.

What will be declined

  • Repair mechanisms. These repositories detect and measure. A PR adding a fix for a failure family is out of scope by design.
  • Findings against named products. Prior-art analogues name a published failure of similar shape, never a vendor's implementation.
  • Unreproducible numbers. Including benchmark timings, which depend on hardware nobody else has.

Security

Report suspected vulnerabilities privately via a GitHub Security Advisory on the relevant repository rather than a public issue. See each repository's SECURITY.md.