Skip to content

Contributing

Two readers — contributors changing the codebase and senior consumers reading for depth. Both meet here.

Two readers. Most pages assume you are about to change the codebase — open a PR that fixes a bug, adds a capability, refactors internals, or bumps a dependency. The same pages double as the deep reference for a senior consumer who wants to understand why the system behaves the way it does before trusting it in production.

What you will not find here: a “how to call the API” tutorial — that’s the Quickstart and the Pytest Fixtures reference. The REST API reference is authoritative for the HTTP surface.

In this section

  •   Your first PR

    The 30-minute path: clone, make check green, find a good-first-issue, ship it. Six checkboxes; everything else is for once you’re past these.

  •   Dev setup

    Clone, make check, code style + type-check rules, CVE-pinned dependency convention, branch-to-PR flow. Run once, return when CI surprises you.

  •   Invariants

    The eight load-bearing rules a change cannot break. Each entry: rule, why, what breaks. Read before touching server.py, lab_manager.py, or connector.py.

  •   Async discipline

    _run_blocking, the async/sync boundary, the single Netlab invocation path. Mechanics behind “long Netlab calls don’t block the queue”.

  •   LabManager

    The classmethod-only singleton, try_acquire vs acquire, GLOBAL_LOCK, stale-state recovery. The synchronous half of the codebase.

  •   atexit & lifespan

    Three teardown paths (lifespan, signal handlers, atexit), why they all stay synchronous, and what silent=True is protecting against.

  •   Test stubbing

    The StubLabManager pattern, the pytest plugin entry point, and why the singleton design makes both possible.

  •   Anti-patterns

    A grep target for code review. Every load-bearing rule restated as a code-review trigger, linked to the page that explains why.

Where contributor knowledge lives

Source Purpose When to read
Invariants + the four Internals pages The rules and the mechanics that enforce them. Before modifying server, queue, or lab-manager code; before reasoning about edge cases as a power consumer.
Anti-patterns A one-page grep target for code review. When reviewing a PR that touches the load-bearing surface.
AGENTS.md The same invariants in repo-root form, alongside agent-bootstrap context. When working with an AI assistant, or when you want a one-screen recap with no narrative.
README.md Project overview, install, quick orientation. First contact.
Source code itself The truth. Trace comments in this section’s pages point at the relevant lines. When the docs and the code disagree — file a docs issue and trust the code.
  • Dev setup — start here if your dev environment is not yet running make check green.
  • Invariants — start here if your dev environment is fine and you are about to change something load-bearing.
  • Architecture — the high-level picture of how the components fit together. The Internals pages assume you have read this.