Contributing

Warning

Pre-implementation. The emma harness is not yet released. The dev setup, contribution flow, and curation layer below describe how contribution will work once src/emma/ lands; the documentation-quality checks already run today.

Who should read this. Anyone who wants to contribute a task, a dataset recipe, a readout head, or a documentation improvement to EMMA (Electromagnetic Multi-task Model Assessment).

Before you start. Read PRINCIPLES.md for the engineering and documentation posture, and STYLE.md for the writing rules every page is held to. Both are enforced by the docs build and lint.

What this section is not. It is not a tutorial for running the harness; see Getting Started once the package ships.

Dev setup

The documentation builds today, before any Python package exists. To preview the docs and run the checks locally:

1. Clone the repository.

2. Create a virtual environment and install the docs dependencies.

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r docs/requirements.txt
   

3. Build the docs with warnings treated as errors.

   PATH="$PWD/.venv/bin:$PATH" bash scripts/docs_build.sh
   

4. Lint the docs.

   python3 scripts/docs_lint.py
   

Both commands must finish clean before a documentation change is ready for review. The exact rules are in Docs quality checks.

Contribution flow: a new task

EMMA follows the BIG-bench (Beyond the Imitation Game benchmark) gated-curation model: a community owns a task, and the steering committee curates it. Adding a task means defining what to measure, not building new infrastructure, because every task runs on the same frozen backbone and the same raw multi-antenna I/Q (in-phase and quadrature) substrate. The step-by-step procedure, from TaskSpec through committee review, lives in Add a task.

The short version:

1. Confirm no existing task already measures your capability (see Task reference).

2. Name a target domain and a real community that depends on the capability. A task with no downstream buyer is a finding, not a feature.

3. Write the TaskSpec, pick a standard-library metric, pick an OOD (out-of-distribution) axis, and pin a dataset recipe.

4. Open a task proposal. The steering committee reviews for construct validity, domain utility, and overlap with existing tasks.

Reuse before defining: search torchmetrics, scipy, numpy, and the established benchmark precedents before proposing a new metric, OOD axis, or task. The smell tests in PRINCIPLES.md name the moments to stop and ask.

Steering-committee curation layer

Curation is gated to keep the aggregate score defensible. At v0.1 the gate is an operational ring-fence: a named external co-steward holds the test-set seed and re-scores every Superpose submission (see Neutrality). At v1 a cross-community steering committee is seated, with one elder per sub-community and a formal conflict-of-interest policy. Accepted tasks ship in the next release with a version badge and a maturity label recorded in the maturity matrix.

The curation layer exists so that the aggregate OOD-avg score remains a meaningful measure of transfer competence. A task added without construct-validity or domain-utility review dilutes the aggregate; the gate is the mitigation.

Documentation changes

Documentation changes follow the same bar as code. Every page is held to the design-review and implementation-blueprint standard in PRINCIPLES.md and STYLE.md, and the build plus lint enforce the mechanical rules. See Docs quality checks for the full contract.