Skip to content

Commit c0930f9

Browse files
committed
docs(sdk): add CONTRIBUTING.md
Examples repo already has one. SDK did not. Covers: - Dev setup (clone, venv, pip install -e .[dev]) - Tests (pytest, source-pin regression pattern reference) - Linting / types (ruff + mypy + pre-commit) - Conventional Commits + prefixes actually used in this repo - PR rules (one logical change, wire-shape changes need ADR reference) - Issue/defect naming and security pointer
1 parent 458ebcb commit c0930f9

1 file changed

Lines changed: 75 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Contributing
2+
3+
Thanks for adding to the NullRun Python SDK. This file covers the
4+
mechanics of landing a change. For product context, see
5+
[README.md](./README.md) and the [docs](https://docs.nullrun.io).
6+
7+
## Development setup
8+
9+
```bash
10+
git clone https://github.com/nullrunio/nullrun-sdk-python
11+
cd nullrun-sdk-python
12+
python -m venv .venv && source .venv/bin/activate
13+
pip install -e ".[dev]"
14+
```
15+
16+
Python 3.10+ is required.
17+
18+
## Tests
19+
20+
```bash
21+
pytest -q # full suite
22+
pytest tests/test_v3_wire_contract.py::TestGateCache -q # single file / class
23+
```
24+
25+
Tests must pass before opening a PR. New public API requires tests —
26+
no exceptions. Source-pin regression tests live alongside the code
27+
they protect (see `tests/test_audit_p0_27_operation_id_hoist.py`
28+
for the canonical pattern).
29+
30+
## Linting and types
31+
32+
```bash
33+
ruff check src tests # lint
34+
ruff format src tests # auto-format
35+
mypy src/nullrun # strict-ish type check
36+
```
37+
38+
CI runs the same three steps plus pre-commit hooks (`trailing-whitespace`,
39+
`end-of-file-fixer`, `check-yaml`, `check-toml`). Do not bypass with
40+
`--no-verify`.
41+
42+
## Commit hygiene
43+
44+
We follow [Conventional Commits](https://www.conventionalcommits.org/).
45+
Common prefixes used in this repo:
46+
47+
| Prefix | Used for |
48+
| ---------- | ----------------------------------------------------- |
49+
| `feat` | New public API or behaviour |
50+
| `fix` | Correctness fixes (cite the defect id) |
51+
| `refactor` | Internal change with no observable behaviour shift |
52+
| `docs` | README / CHANGELOG / docstring-only changes |
53+
| `test` | New or rewritten tests |
54+
| `chore` | Release prep, dep bumps, CI plumbing |
55+
56+
Reference the defect id in the body when one exists
57+
(`DEF-OPID-REUSE-HASH-MISMATCH`, `NR-007`, …).
58+
59+
## Pull requests
60+
61+
- One logical change per PR. Drive-bys bundled into unrelated PRs get
62+
rejected at review.
63+
- PR description: what changed, why, how to verify, any wire-shape or
64+
ADR implications.
65+
- Wire-contract changes (anything that touches `_V3_ERROR_CODE_MAP`,
66+
`transport.py`, the gate payload shape, or `runtime.check_workflow_budget`)
67+
require an ADR reference. Coordinate before opening.
68+
69+
## Issues
70+
71+
- Use the GitHub issue templates.
72+
- Defects use the `DEF-*` prefix in the title. Probes / Q&A go to the
73+
relevant `qa/` subtree in `nullrun-examples` — not this repo.
74+
- Security issues do **not** belong in public issues — see
75+
[SECURITY.md](https://github.com/nullrunio/.github/blob/main/SECURITY.md).

0 commit comments

Comments
 (0)