Contributing

Contributing

Dev setup

git clone https://github.com/ClappFormOrg/clappform-python.git
cd clappform-python
pip install -e .[dev,pandas]

Python 3.10+ (CI verifies 3.10–3.14 on Linux and Windows).

Everyday commands

make check       # ruff + mypy + pytest (the full local gate)
make generate    # regenerate clappform/gen and clappform/services from protos
make test        # pytest only

Regeneration needs a commons clone; point CLAPPFORM_COMMONS_DIR at it or keep it as a sibling ../commons. See Code Generation.

Branching & PRs

• Base branch for v6 work: Major/6. Branch from it, PR back into it.
• Branch names: feat/…, fix/…, chore/… with a short kebab-case slug.
• Conventional-commit messages (feat:, fix:, chore:). Group work into logical commits, not one blob.
• Open PRs as draft first; link issues with Closes #N (fully delivered) or Implements #N (partial). Major/6 is a non-default base, so fully delivered issues are closed when the PR merges.
• Every PR is green on make check before review.

Where things live

• Design decisions: the Design spec — edit there, reference by section from issues and PRs. Don't restate decisions in issue bodies.
• What to work on next: Roadmap & Status.
• Generated code: never edit by hand; change the protos or the generator.
• Tests: unit tests plus an in-process gRPC server for transport-level behaviour — match the neighbouring style. See Design §8.

Terms

New to the codebase? Start with the Glossary — the cluster/location and family/service distinctions are load-bearing.