CONTRIBUTING.md

Contributing

This is a capstone project; the workflow is deliberately strict so main stays clean and every change is reviewable.

Branch model

• main is protected by convention — never push to it directly. It only moves via reviewed merges from a feature branch.
• Feature branches are named checkpoint-<N>-<short-desc> where:
  • <N> is a monotonically increasing integer (so the history reads in order).
  • <short-desc> is a 2–4 word kebab-case summary, e.g. checkpoint-2-refactor-and-docs, checkpoint-3-fastapi-demo.
• The first checkpoint (checkpoint-1-baseline) snapshots the state of main at v0.1.0 so we have an immutable reference point before any new work.

Workflow

# 1. Find the next N
git fetch origin
git branch -r | grep -E 'origin/checkpoint-[0-9]+-' | sort
# 2. Branch off main
git checkout main && git pull
git checkout -b checkpoint-<N>-<short-desc>
# 3. Make changes, run tests, commit
pytest -q
git commit -m "..."
# 4. Push and open a PR
git push -u origin checkpoint-<N>-<short-desc>
gh pr create --base main --title "..." --body "..."
# 5. Reviewer merges via the GitHub UI / `gh pr merge`

Commit hygiene

• Run pytest -q before each commit. We require all tests to pass on main.
• Keep commits scoped — one concern per commit; bigger changes go in multiple commits on the same branch.
• No secrets, no large artifacts. Model weights belong in GitHub releases; raw data lives in data/raw/ which is gitignored.

Code style

The project optimises for readable, small files over clever abstractions. Concrete preferences:

• KISS — prefer two clear lines over one clever expression. Each module should be readable end-to-end in under 5 minutes.
• Single responsibility — files do one job. ccdp.utils.device only picks devices; ccdp.utils.transforms only builds torchvision pipelines.
• Shared base classes only when there's real duplication. BaseVariantPipeline exists because Variant A and B genuinely share the XGBoost + FX + provenance flow; we don't manufacture base classes for things that happen to look similar.
• Docstrings on every module explain what the module is for and why it exists separately from its neighbours, not how every line works.
• Type hints on public surfaces. Internal helpers can skip annotations when the type is obvious from context.
• No emojis in source code (PRs and chat are fine).

Testing

• pytest -q runs the full suite — currently 64 tests.
• Tests live in tests/ and use only pytest (no plugins beyond pytest-cov which is optional).
• Network / GPU / large-dataset tests are skipped when their prerequisites are absent (see the @pytest.mark.skipif guards on Stanford Cars / iaai tests).
• New behaviour needs at least one test; complex new logic needs a few.

Trained models

• Don't commit weights to git. Use GitHub Releases.
• Each release version corresponds to a tag on main. Use gh release create vX.Y.Z with weights attached as assets.
• Promotion via ccdp registry promote <run_id> <variant> is the only thing that should move the checkpoints/production/<variant>.pt symlink.

Project structure

See README.md for the source-tree layout and execution flow. For the rationale behind each phase, see PLAN.md and the per-phase status docs under progress/.