# Contribution checklist

Use this checklist before opening or merging a MoDaCor change.

## Environment

- Work against Python 3.12 or newer.
- Install the local development extras you need:

```bash
uv pip install -e ".[tests,lint,docs]"
```

## Code and tests

- Run the focused tests for the area you changed.
- Run the full suite before merging:

```bash
python -m pytest -q
```

- Run linting for touched files:

```bash
python -m flake8 src/modacor tests
python -m isort --check-only --diff --filter-files src/modacor tests
```

## Documentation

- Update user-facing docs when CLI, runtime-service, pipeline behavior, or
  extension contracts change.
- Use `docs:` as the commit prefix for documentation-only changes that should
  be classified as documentation updates in generated release notes.
- If you add or change a public `ProcessStep`, regenerate the module reference
  pages:

```bash
python scripts/generate_module_doc.py --all --output-dir docs/reference/modules --index docs/reference/modules/index.md
python scripts/generate_module_doc.py --all --output-dir docs/reference/modules --index docs/reference/modules/index.md --check
```

- Rebuild the docs and confirm there are no warnings:

```bash
python -m sphinx -E -W --keep-going -b html docs dist/docs
```

## Review points

- Keep `modacor.modules.__all__` aligned with the intended public step surface.
- Keep package dependencies one-way: modules may use models, geometry, and IO;
  models may use geometry; geometry must remain format- and pipeline-independent.
- Promote reusable mathematics out of `ProcessStep` methods, and do not import
  private helpers from one process-step module into another.
- Keep non-step pipeline adapters under `modacor.modules.helpers`; keep retired
  steps under `deprecated` and out of `modacor.modules.__all__`.
- Keep NeXus/HDF5 traversal in `modacor.io`, even when the values it resolves
  ultimately describe geometry.
- Keep CLI and runtime-service paths aligned when they share request or IO
  behavior.
- Preserve docstrings and type hints when simplifying code.
- Avoid leaving unfinished pages or stale backlog state after structural
  refactors.

## Release notes

- Do not manually edit `CHANGELOG.md` for ordinary PRs. The release-preparation
  workflow generates a dedicated release PR after changes reach `main`.
- Use semantic commit prefixes that match the project configuration:
  `fix:`/`perf:` for patch releases, `enh:`/`feat:` for minor releases, and
  `docs:` for documentation entries.
- Mark an incompatible public interface with a conventional breaking-change
  marker (`type!:` and/or a `BREAKING CHANGE:` footer), and link its migration
  guidance from the PR. A plain `feat:` commit does not communicate the
  required major-version impact.
- Review and merge the generated release PR before expecting a new version tag
  or PyPI publication.