Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
55 lines (39 loc) · 2.13 KB

CONTRIBUTING.md

File metadata and controls

55 lines (39 loc) · 2.13 KB
Raw

Contributing to OpenVariance

Thanks for helping. OpenVariance is used to explain real companies' numbers, so correctness comes first: every number has to tie, and every new calculation needs a test that proves it.

Getting set up

git clone https://github.com/wavebyrd/openvariance && cd openvariance
uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest

On Windows the tools live in .venv\Scripts\ instead of .venv/bin/. CI runs on both Linux and Windows, so open files with an explicit encoding="utf-8".

Before opening a pull request, run:

.venv/bin/ruff format . && .venv/bin/ruff check . && .venv/bin/mypy && .venv/bin/pytest

What makes a good change

  • Tests that state the invariant. If a calculation should reconcile, balance or tie, write the test that way. Use Hypothesis when it holds for any input (see tests/test_attribution.py and tests/test_forecast.py).
  • Decimal for money. No floats in the engine. Attribution uses Fraction for exact math.
  • No silent fixes. If data doesn't tie, report a failed Check with the difference. Don't plug it.
  • Documented formulas. If you change or add a calculation, update docs/methodology.md in the same pull request.
  • Plain language. Error messages say what happened and what to do next.

Good first contributions

  • New accounting-system presets for the importer, with a sample export in tests/fixtures
  • More us-gaap tags for SEC lines that companies report under unusual names
  • Mapping keyword rules for industries that aren't covered yet (retail, healthcare, nonprofits)

Changing the demo data

Demo Co. is generated by scripts/make_demo_data.py. Edit the script and rerun it. Don't edit the CSVs by hand.

Reporting a bug

Please include the command or tool call, what you expected, what happened, and if possible a small file that reproduces it with made-up numbers. Never attach real company financials to a public issue.

Code of conduct

Be kind and assume good intent. Harassment or discrimination of any kind isn't tolerated. Maintainers may remove comments or contributors that break this.