Skip to content

Contributing to ZADU

Bug fixes, documentation improvements, performance work, and new distortion measures are welcome.

Propose a metric without writing code

Open the metric proposal form and provide:

  • the metric name;
  • the paper or another authoritative description; and
  • the reference implementation, if one exists.

For example:

Please add the Gap Index.

Paper: https://arxiv.org/abs/2607.28324
Reference implementation: https://codeberg.org/jros/gap-index

Maintainers review the definition, license, and integration requirements. Include any known difference between the paper and its implementation.

Every metric contribution must include evidence of correctness: an independent slow oracle, results pinned to a reference implementation revision, or analytical examples. Original authors and compatible upstream licenses must be credited, and adaptations must be described.

Development setup

Use Python 3.10 or newer and install the development and documentation dependencies:

python -m pip install -e ".[dev,docs]"

Before opening a pull request, run:

python -m pytest test/test_metric_contract.py -q
python -m pytest
ruff check .
black --check src test scalability_eval benchmarks
python -m mkdocs build --strict

Coding agents should also follow AGENTS.md, which contains the repository-specific metric integration checklist. Pull requests should explain the user-visible change, the verification performed, and any compatibility, performance, numerical, citation, or licensing implications.