| # Contributing to OrgState |
|
|
| ## Dev setup |
|
|
| ```bash |
| # clone + install runtime deps + test deps |
| pip install -r requirements-runtime.txt |
| pip install pytest |
| |
| # install pre-commit hooks (Stage 94) — runs ruff lint+format |
| # and basic file hygiene before every commit |
| pip install pre-commit |
| pre-commit install |
| |
| # now `git commit` automatically runs the hooks |
| ``` |
|
|
| ## Style |
|
|
| - **Python**: ruff handles lint + format (config in `pyproject.toml`). No black / isort / flake8 — ruff replaces all three. |
| - **Line length**: 100. Existing long lines grandfathered (E501 deferred); new code stays under. |
| - **Hebrew for chat / commit body OK**. Code identifiers + comments stay English. |
|
|
| ## Pre-commit hooks — what they enforce |
|
|
| | Hook | What | Why | |
| |---|---|---| |
| | `ruff` | Lint with `--fix` | Auto-fixes safe issues (sort imports, remove unused, etc) | |
| | `ruff-format` | Format like black | Eliminates style bikeshedding | |
| | `trailing-whitespace` | Strip trailing spaces | Cleaner diffs | |
| | `end-of-file-fixer` | Ensure final newline | POSIX text files | |
| | `check-yaml` / `check-json` / `check-toml` | Parse config files | Catches typos before push | |
| | `check-added-large-files` | Refuse > 500KB | Repo bloat guard | |
| | `check-merge-conflict` | Catch unresolved `<<<<<` | Pre-flight check | |
| | `detect-private-key` | Refuse SSH/PGP keys | Defense against leaks | |
|
|
| ## Run hooks manually |
|
|
| ```bash |
| # run on all files (first time after installing) |
| pre-commit run --all-files |
| |
| # run only on staged files (default behavior — git commit triggers) |
| pre-commit run |
| |
| # skip hooks for an emergency commit (use sparingly) |
| git commit --no-verify |
| ``` |
|
|
| ## Running tests |
|
|
| ```bash |
| # full suite |
| pytest |
| |
| # one file |
| pytest tests/test_infra_billing.py |
| |
| # coverage subset |
| pytest -k webhook |
| |
| # skip slow tests (npm build, locust import, etc — gated by |
| # tool availability already, but you can be explicit) |
| pytest -m "not slow" |
| ``` |
|
|
| The CI pipeline runs the full suite against both SQLite and Postgres on every PR — see `.github/workflows/ci.yml`. If pre-commit hooks pass locally, CI usually does too. |
|
|
| ## Adding a new stage |
|
|
| 1. Plan the work in MIGRATION_MAP.md (per-stage narrative is part of the deliverable). |
| 2. Code + tests in same commit. Test count goes UP on every stage. |
| 3. Run `pre-commit run --all-files` + `pytest` before committing. |
| 4. Commit message format: `Stage N: <title>` + body explaining the WHY (see git log for examples). |
| |
| ## When ruff finds something |
| |
| - **Auto-fixable** (most I/F rules): `ruff check . --fix` and commit. |
| - **Manual fix needed**: address the underlying issue. Don't `# noqa: X` unless there's a good reason — the rule probably matters. |
| - **Codebase-wide false positive**: add to `[tool.ruff.lint.ignore]` or `per-file-ignores` in `pyproject.toml`, with a comment explaining the trade-off. |
| |
| ## License + provenance |
| |
| All commits become part of the project history under the repo's existing license. By contributing, you agree your changes can be redistributed under that license. |
| |
| For questions: see `RUNBOOK.md` (operator concerns) or `MIGRATION_MAP.md` (per-stage decisions). |
|
|
