CONTRIBUTING.md

Contributing to Co-Study4Grid

Thanks for taking the time to contribute. This document captures the conventions that keep the codebase easy to work in. For the project overview and architecture see CLAUDE.md.

Development setup

Backend

python -m pip install --upgrade pip
pip install ".[test]"
pip install --no-deps expert_op4grid_recommender
uvicorn expert_backend.main:app --host 0.0.0.0 --port 8000

System prerequisite — Graphviz (dot)

The overflow-graph rendering pipeline shells out to Graphviz's dot binary. pip install attempts a best-effort auto-install via the platform's package manager (apt / dnf / pacman / apk on Linux, Homebrew or MacPorts on macOS, Chocolatey / winget / Scoop on Windows); set COSTUDY4GRID_SKIP_GRAPHVIZ_INSTALL=1 to opt out. Modern wheel-based installs may skip the setup.py post-install hook — re-run it manually with the bundled console script if dot -V fails:

costudy4grid-install-graphviz

If the auto-install can't elevate (no sudo, locked package DB, unsupported package manager), install Graphviz by hand:

Platform	Command
Debian / Ubuntu	sudo apt-get install graphviz
RHEL / Fedora	sudo dnf install graphviz (or yum)
Arch	sudo pacman -S graphviz
Alpine	sudo apk add graphviz
macOS (Homebrew)	brew install graphviz
macOS (MacPorts)	sudo port install graphviz
Windows (Chocolatey)	choco install graphviz
Windows (winget)	winget install Graphviz.Graphviz
Windows (Scoop)	scoop install graphviz

Frontend

cd frontend
npm install
npm run dev    # Vite dev server with HMR (default port 5173)

Running tests

# Backend
pytest

# Frontend
cd frontend
npm run test
npm run lint

Code-quality checks

Continuous quality metrics are generated by scripts/code_quality_report.py and enforced by scripts/check_code_quality.py. Both run locally and in CI (see .github/workflows/code-quality.yml).

# Generate a full JSON + Markdown report
python scripts/code_quality_report.py --output reports/code-quality.json \
                                      --markdown reports/code-quality.md

# Gate a pull request (non-zero exit on regression)
python scripts/check_code_quality.py

The gate enforces (full table in scripts/check_code_quality.py):

• No new print() or traceback.print_exc() calls in backend sources
• No new bare except Exception: pass patterns
• Backend modules stay under 1150 lines (the "god-object" ceiling); functions under 240. The scan covers all of expert_backend/ except the test suite and the setup-time / ad-hoc scripts.
• Backend functions also stay under cyclomatic complexity 38 and nesting depth 8 (computed from the AST — no external tool).
• Frontend components stay under 1450 lines (utils/** under 1000); App.tsx, the orchestration hub, has a bounded 2100 ceiling rather than a blanket exemption.
• No any / as any annotations, and no @ts-ignore / @ts-expect-error / @ts-nocheck in frontend sources
• Ratcheted (frozen at today's count, may only go down): backend # noqa / # type: ignore (3), as unknown as casts (12), Record<string, unknown> usages (45)
• No hex color literals in frontend source. The ceiling is zero — every colour must come from a named token. Define new colours in frontend/src/styles/tokens.css (the canonical CSS variables) and re-export them from frontend/src/styles/tokens.ts for inline-style consumers (colors / space / text / radius, plus pinColors / pinChrome for SVG-attribute use cases). Both token files are exempt from the gate; nothing else is.

Lower the thresholds — don't raise them. Tightening the gate is how we protect the hard-won reductions documented in docs/architecture/code-quality-analysis.md.

mypy gates the build. The shared-state base (expert_backend/services/_recommender_state.py) makes the mixin composition type-check cleanly, so mypy sits at 0 and any new type error fails CI. Test coverage gates on both ends: frontend via frontend/vite.config.ts (coverage.thresholds, enforced by npm run test:coverage) and backend via pyproject.toml ([tool.coverage.report] fail_under = 72, enforced by pytest --cov). Both floors sit a few points below the measured baseline — raise them as coverage climbs, don't lower them. All are wired into the GitHub Actions pipelines; see §§19–20 of the analysis doc.

Commit & PR conventions

• Conventional-commit prefixes: feat:, fix:, perf:, docs:, test:, refactor:, build:, chore:. Match the surrounding git log.
• Keep PRs focused. One logical change per PR.
• Run pytest, npm run test, npm run lint, and python scripts/check_code_quality.py before opening a PR.
• Update docs/architecture/code-quality-analysis.md when a fix resolves a documented issue.

Style

• Python: PEP 8 manually (4-space indent, type hints where helpful, snake_case). Use logging, not print. Ruff runs in CI with a light ruleset — see pyproject.toml.
• TypeScript: strict mode (strict: true, noUnusedLocals, noUnusedParameters). No any. Functional components + hooks. ESLint flat config enforces the rest.
• Editor defaults live in .editorconfig.

Reporting bugs

Open a GitHub issue with:

1. Steps to reproduce (network path, action file, settings, contingency).
2. Expected vs. actual behaviour.
3. Browser console + backend stderr when UI-related.
4. The attached session folder when reproducible via save/reload.