From 458ebcb4bd9f1643ad943dd2edbd08c0d76505bb Mon Sep 17 00:00:00 2001 From: Anatolii Date: Tue, 15 Sep 2026 22:21:50 +0400 Subject: [PATCH 1/2] docs(sdk): sync status banner to v0.17.1 and roadmap Latest release is v0.17.1 (2026-09-15). README was lagging: - Status banner said v0.16.4 - Roadmap marked v0.17 as planned (already shipped) Move v0.17.x to current with the actual shipped content (chain-setter Token, _GATE_CACHE staleness closure, lazy-export repair, CB lock unification, op_id mint-fresh, error-code map closure). Move OpenTelemetry / Redis queue / hardened init to v0.18 planned. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6a12142..e58c521 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ LlamaIndex, and your own stack. --- -> ⚠️ **Status: alpha (v0.16.4).** The public API may shift between minor versions. +> ⚠️ **Status: alpha (v0.17.1).** The public API may shift between minor versions. > Pin your dependency and read the [CHANGELOG](https://github.com/nullrunio/nullrun-sdk-python/blob/master/CHANGELOG.md) before upgrading. --- @@ -294,8 +294,9 @@ Runnable, copy-pastable examples live in a separate repo so you can adapt withou |---|---|---| | **v0.14.x** | ✅ alpha | Wire protocol v3.31, server-minted execution IDs, MCP, anti-OOM streaming cap | | **v0.15.x** | ✅ alpha | ADR-009 governance audit surface, typed `runtime.audit.*`, capability probes for `/audit-log/verify`, fail-OPEN observability closure | -| **v0.16.x** (current) | ✅ alpha | Phase-1+ `action_digest` on `/gate`, `/execute` `tools` propagation, transient-5xx retry on gate (NR-006), error-code parity (NR-007, 41→56 entries) | -| **v0.17** | 📋 planned | OpenTelemetry exporter, Redis-backed offline queue, hardened init contract | +| **v0.16.x** | ✅ alpha | Phase-1+ `action_digest` on `/gate`, `/execute` `tools` propagation, transient-5xx retry on gate (NR-006), error-code parity (NR-007, 41→56 entries) | +| **v0.17.x** (current) | ✅ alpha | Chain-setter Token discipline, `_GATE_CACHE` staleness closure, lazy-export repair, circuit-breaker lock unification (sync+async), op_id mint-fresh (DEF-OPID-REUSE-HASH-MISMATCH), error-code map closure (DEF-SDKT-004) | +| **v0.18** | 📋 planned | OpenTelemetry exporter, Redis-backed offline queue, hardened init contract | | **v1.0** | 🎯 beta target | Stable wire contract, full async support, type-safe decisions | [Full roadmap & RFCs →](https://nullrun.io/roadmap) From c0930f989034ecd4915f3296d1c159083c1f1793 Mon Sep 17 00:00:00 2001 From: Anatolii Date: Tue, 15 Sep 2026 22:21:50 +0400 Subject: [PATCH 2/2] 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 --- CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..04212c5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing + +Thanks for adding to the NullRun Python SDK. This file covers the +mechanics of landing a change. For product context, see +[README.md](./README.md) and the [docs](https://docs.nullrun.io). + +## Development setup + +```bash +git clone https://github.com/nullrunio/nullrun-sdk-python +cd nullrun-sdk-python +python -m venv .venv && source .venv/bin/activate +pip install -e ".[dev]" +``` + +Python 3.10+ is required. + +## Tests + +```bash +pytest -q # full suite +pytest tests/test_v3_wire_contract.py::TestGateCache -q # single file / class +``` + +Tests must pass before opening a PR. New public API requires tests — +no exceptions. Source-pin regression tests live alongside the code +they protect (see `tests/test_audit_p0_27_operation_id_hoist.py` +for the canonical pattern). + +## Linting and types + +```bash +ruff check src tests # lint +ruff format src tests # auto-format +mypy src/nullrun # strict-ish type check +``` + +CI runs the same three steps plus pre-commit hooks (`trailing-whitespace`, +`end-of-file-fixer`, `check-yaml`, `check-toml`). Do not bypass with +`--no-verify`. + +## Commit hygiene + +We follow [Conventional Commits](https://www.conventionalcommits.org/). +Common prefixes used in this repo: + +| Prefix | Used for | +| ---------- | ----------------------------------------------------- | +| `feat` | New public API or behaviour | +| `fix` | Correctness fixes (cite the defect id) | +| `refactor` | Internal change with no observable behaviour shift | +| `docs` | README / CHANGELOG / docstring-only changes | +| `test` | New or rewritten tests | +| `chore` | Release prep, dep bumps, CI plumbing | + +Reference the defect id in the body when one exists +(`DEF-OPID-REUSE-HASH-MISMATCH`, `NR-007`, …). + +## Pull requests + +- One logical change per PR. Drive-bys bundled into unrelated PRs get + rejected at review. +- PR description: what changed, why, how to verify, any wire-shape or + ADR implications. +- Wire-contract changes (anything that touches `_V3_ERROR_CODE_MAP`, + `transport.py`, the gate payload shape, or `runtime.check_workflow_budget`) + require an ADR reference. Coordinate before opening. + +## Issues + +- Use the GitHub issue templates. +- Defects use the `DEF-*` prefix in the title. Probes / Q&A go to the + relevant `qa/` subtree in `nullrun-examples` — not this repo. +- Security issues do **not** belong in public issues — see +[SECURITY.md](https://github.com/nullrunio/.github/blob/main/SECURITY.md).