Skip to content
grid-diamondcutter

Contributor walkthrough

You want to add a new measurement. The project takes pull requests.

The contribution shape

A measurement is one Python file in examples/voices/ (for phase-A measurements) or phase_2/examples/voices/ (for the monetary-substrate extension). The file has four parts:

  1. The prediction: what the measurement expects to find.
  2. The kill condition: the result that would prove the prediction wrong, expressed as something the code can check.
  3. The code: how the measurement is computed.
  4. The verdict: pass, fail, or partial, computed mechanically.

The prediction and the kill condition must be written before the code runs. After the code runs, a small JSON file is written alongside the Python file. That JSON file carries a hash that locks the pre-code state in place.

The template

Start from examples/voices/_voice_template.py. There is a step-by-step walkthrough at docs/voice_authoring_guide.md.

The test you must pass

Before opening a pull request, run:

Terminal window
python -m pytest tests/test_voice_registry_contract.py -k <your_voice_name>

This checks that your file has the four parts named above, that the code runs without crashing, and that the JSON hash matches the pre-result state.

What happens after you open the pull request

A reviewer will:

  1. Check that the test passes.
  2. Read the prediction and the kill condition. The kill condition must be tight enough that a wrong prediction would actually fail.
  3. Read the rationale and the scope. The measurement must respect the boundaries.
  4. Merge once both pass.

If your measurement fails its prediction, that is not a reason to reject the pull request. About six out of ten of the measurements in this project failed their predictions. Both kinds are kept.

The contributing reference

The reference document is CONTRIBUTING.md.