Contributing#
OOWL welcomes code, documentation, scientific validation, and well-supported bug reports. Read the design philosophy before changing the domain model and the coding style before implementing a change.
Set up and validate#
Create a focused branch from an up-to-date main, then install the locked
development environment.
git switch main
git pull --ff-only
git switch -c feature/short-description
pixi install --locked --environment dev
Before opening a merge request, run the relevant compatibility suites and the standard development gate.
pixi run --environment dev lint
pixi run --environment dev format-check
pixi run --environment dev typecheck
pixi run --environment dev test
pixi run --environment dev docs
pixi run --environment minimum test-minimum
pixi run --environment dev build
pixi run --environment dev check-dist
Explain any check that does not apply or cannot run. The pipeline also validates newer Python, the clean wheel, and relevant windIO and GWA/PyWake compatibility.
That gate is the pre-merge check, not the edit loop. docs executes every
notebook and takes minutes. While editing prose, navigation or docstrings, use
the same -nW build with execution switched off.
pixi run --environment dev docs-fast
It checks every reference, toctree, docstring and redirect in about fifteen
seconds. It cannot see changed outputs, so run the full docs before pushing
anything that alters a figure or a printed value.
Prepare the change#
Keep commits small and named for the behavior they introduce.
Add tests for changed behavior and regression tests for fixed bugs.
Update the user documentation and
CHANGELOG.mdfor public changes.Do not commit raw datasets, local environments, generated study outputs, or unrelated files.
Describe new scientific methods, assumptions, fitting cohorts, validation, and limitations. State the source and license of external data or code.
Use a draft merge request for work that needs design feedback. The final description should state what changed, why, and which checks were run.
AI-assisted contributions#
AI tools may assist development, but a human contributor must review and take responsibility for the design, correctness, tests, licensing, and submitted changes. Briefly disclose substantial AI assistance in the merge request. AI systems are tools, not contributors or software authors.