Contributing to ZADU¶
Bug fixes, documentation improvements, performance work, and new distortion measures are welcome.
Propose a metric without writing code¶
You do not need to understand ZADU's internals or prepare a specification file. 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
That is enough for a coding agent or maintainer to investigate the formula, license, attribution, validation rules, integration, tests, documentation, and whether an existing accelerated execution resource can be reused. Contributors do not need to understand the execution planner. Questions should be limited to scientific or licensing ambiguities that the provided sources cannot resolve.
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:
Before opening a pull request, run:
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.