# Contributing

OOWL welcomes code, documentation, scientific validation, and well-supported
bug reports. Read the [design philosophy](design.md) before changing the domain
model and the [coding style](coding-style.md) before implementing a change.

## Set up and validate

Create a focused branch from an up-to-date `main`, then install the locked
development environment.

```bash
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.

```bash
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.

```bash
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.md` for 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.

## Credit and citation authorship

Git commits and merge requests retain detailed contribution history. The
software-author list in `CITATION.cff` is curated by the maintainers and is not
derived from commit counts.

An accepted author remains credited in later releases because new versions
build on earlier work. New authors are normally appended in the order approved
by the maintainers. Reordering requires agreement from the existing authors.
Small fixes and reviews are valuable but do not automatically confer citation
authorship.