Skip to content

Latest commit

 

History

History
828 lines (682 loc) · 48.2 KB

CONTRIBUTING.md

File metadata and controls

828 lines (682 loc) · 48.2 KB

Contributing to Pyrite

Thank you for considering contributing to Pyrite! This guide will help you get started.

Before a change, read Pyrite's design principles.

If you find Pyrite valuable, please also star the repository. It costs nothing, and it is one of the signals people use to decide whether a project is worth their time.

Development Setup

Prerequisites

  • Python 3.11+ (3.13 recommended)
  • Git
  • uv (recommended) or pip

Initial Setup

The quickest path is scripts/setup-checkout.sh after cloning: it makes the venv, installs the extensions and writes the repo-local .pyrite/config.yaml that makes pyrite -k pyrite mean this checkout's kb/ (the KB lookups in AGENTS.md need it). It installs no git hooks: after it, run .venv/bin/pre-commit install. The manual steps, if you prefer them:

# Clone the repository
git clone https://github.com/pyrite-wiki/pyrite.git
cd pyrite

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
# `.[all]` is the whole optional surface (CLI, server, MCP, AI) plus the test
# tooling. `.[dev]` alone is tooling only and cannot even collect the suite.
uv pip install -c "$(scripts/lock-constraints.sh)" -e ".[all]"

# Install all extensions (required for full test suite)
for ext in extensions/*/; do uv pip install -c "$(scripts/lock-constraints.sh)" -e "$ext"; done

# Install the git hooks (commit, commit-msg and pre-push in one go)
pre-commit install

# Register this checkout's kb/ as the `pyrite` KB (idempotent; also writes the
# repo-local .pyrite/config.yaml). Without it, `pyrite sw backlog -k pyrite`
# returns KB_NOT_FOUND.
scripts/setup-checkout.sh
pyrite kb list   # the `pyrite` KB path must be this checkout's kb/

# Verify imports resolve to this checkout, including every extension
.venv/bin/python scripts/check_checkout_imports.py

# Verify installation
scripts/heavy_lock.py -- .venv/bin/pytest tests/ extensions/*/tests/ -n 4 -q

Pytest prints the current collected and passed test counts in its summary; they change as the project and extensions grow.

The dependency lock

uv.lock pins every dependency, transitive ones included, to one version for all of Python 3.11, 3.12 and 3.13 (#1357). CI and scripts/setup-checkout.sh install with -c "$(scripts/lock-constraints.sh)", which exports the lock as pip constraints on the spot, so two runs a day apart test the same code. Nothing derived is committed (it would go stale when Dependabot bumps uv.lock). The install verb is still uv pip install -e; uv sync is not used, so the extensions (separate packages with no dependencies of their own) and --system installs work as before. Without uv on your PATH, setup-checkout.sh puts a private uv in the venv with pip and carries on. pyproject.toml keeps its ranges, they are the contract with people who pip install pyrite, and the published wheel does not read the lock.

After you add or change a dependency, or bump the project version, in pyproject.toml, refresh the lock and commit it with the change:

scripts/lock-deps.sh            # uv lock: re-resolves only what pyproject.toml forces
scripts/lock-deps.sh --upgrade  # moves every pin to the newest allowed version
scripts/lock-deps.sh --check    # what CI's `lock` job runs: fails if the lock is stale

tests/test_dependency_lock.py fails offline when a declared dependency is missing from the lock or pinned outside its range; the lock CI job runs uv lock --check, and so does scripts/release.py on the release commit (a version bump leaves the lock stale until you run scripts/lock-deps.sh). Dependabot's uv entry bumps the lock only (versioning-strategy: lockfile-only). The lock does not hide upstream breakage from us: the weekly unlocked.yml workflow installs .[all] without it and runs the suite, so a release inside our ranges that breaks Pyrite shows up there. Dependabot's uv ecosystem (.github/dependabot.yml) opens one grouped weekly PR that updates uv.lock; the lock job and the install jobs run on it like any PR.

See Setting Up the Development Environment for troubleshooting. Line endings are normalised to LF across platforms via repository .gitattributes.

scripts/setup-checkout.sh does the venv, the extensions and a repo-local .pyrite/config.yaml (so pyrite -k pyrite means this checkout's kb/) in one step; scripts/new-worktree.sh <branch> creates a worktree and runs it.

Developing in Claude Code on the web

A cloud session at claude.ai/code comes in two halves: a setup script you paste into the environment once (the slow part, cached as a snapshot), and a SessionStart hook in the checked-in .claude/settings.json (the cheap part, every session).

Create the environment (environment settings at claude.ai/code): keep the default "Trusted" network level, and paste this one line as the setup script:

curl -fsSL https://raw.githubusercontent.com/pyrite-wiki/pyrite/dev/scripts/cloud-env-setup.sh | bash

It builds .venv (pyrite and every in-repo extension), the pre-commit hook environments and pulls the Postgres image, in parallel (9 s on a laptop with a fast network), far inside Anthropic's five-minute cache limit. Skip it and sessions still work, only slower: the hook then does the install itself.

What the hook does (scripts/cloud-session-start.sh; nothing outside a cloud session): reinstalls only if a pyproject.toml changed since the snapshot, writes .pyrite/config.yaml so pyrite -k pyrite means this checkout's kb/, syncs the index, installs the git hooks, puts .venv/bin on PATH, and starts Postgres.

  • Postgres tests run here. The hook starts a pgvector/pgvector:pg16 container (the image, user, password and database CI uses, so a cloud pass predicts a CI pass) and exports PYRITE_TEST_PG_URL once it accepts connections. If Docker or the container fails, the session starts anyway with one warning and those tests skip. Set PYRITE_SETUP_POSTGRES=0 in the environment's variables to opt out. Details: scripts/cloud-postgres.sh.
  • Embeddings are off by default: sentence-transformers pulls torch; the tests that need it skip. For them, set PYRITE_SETUP_EXTRAS=all,postgres and add huggingface.co to the environment's allowed domains.
  • The VM has 4 vCPUs and 16 GB RAM: run one test suite at a time, with -n 4 (the pre-push hook already does).
  • Frontend: run npm ci in web/ when your change touches it.
  • Branches: the session's own branch is fine for a PR to dev; name it fix/* or feature/* if you create one yourself. One session is one checkout, so there is no worktree to make.

Moving work to a worktree

Every worktree of a clone shares the same stash stack. A clean checkout's git stash push creates no entry: a subsequent bare git stash pop would apply and remove somebody else's stash (#1063). Use a unique handoff marker and the matching commit object, never the current top of the stack:

# Replace both placeholders; the token must be unique to THIS handoff.
git stash push --include-untracked -m "handoff-<branch>-<unique-token>"
git stash list --format='%H %gs'
# Record the hash of the entry containing that exact marker.
# If there is no matching entry (nothing was stashed), do not apply anything.
scripts/new-worktree.sh <branch>
git -C <new-worktree-path> stash apply --index <recorded-stash-hash>

apply --index restores staged changes too and keeps the stash for recovery. An interleaved push in another worktree cannot change which commit the recorded hash names. On a conflict, resolve it in the destination and keep the stash until the files and staging are verified. For later cleanup, inspect git stash list again and drop only the entry with that marker; its numeric stash@{N} position may have moved. Do not pop or clear the shared stack. --include-untracked includes untracked files, but not ignored files; copy any needed ignored file explicitly after checking its contents.

Code Standards

Style

We use ruff for linting and formatting:

# Check for issues
ruff check pyrite/

# Auto-fix issues
ruff check --fix pyrite/

# Format code
ruff format pyrite/

Type Hints

  • Use modern Python type hints (3.11+ syntax)
  • list[str] not List[str]
  • str | None not Optional[str]
  • dict[str, Any] not Dict[str, Any]

Imports

  • Use absolute imports within the package
  • Group imports: stdlib, third-party, local
  • Let ruff sort imports automatically

Architecture

Layer Structure

pyrite/
├── models/          # Data models (Entry, core types, factory)
├── storage/         # File and database operations
│   ├── database.py  # PyriteDB: SQLAlchemy ORM + mixin-based modules
│   ├── repository.py # KBRepository: markdown files with YAML frontmatter
│   ├── index.py     # IndexManager: builds/syncs index from markdown
│   ├── migrations.py # MigrationManager: custom schema versioning
│   └── backends/    # SearchBackend protocol + implementations
│       ├── protocol.py        # SearchBackend structural protocol
│       ├── sqlite_backend.py  # SQLiteBackend (default: FTS5 + sqlite-vec)
│       └── postgres_backend.py # PostgresBackend (server: tsvector + pgvector)
├── services/        # Business logic (search, KB ops, QA, schema, etc.)
├── plugins/         # Plugin protocol, registry, context (DI)
├── cli/             # CLI commands (Typer sub-apps)
├── server/
│   ├── api.py       # FastAPI app factory
│   ├── endpoints/   # Per-feature REST endpoint modules
│   └── mcp_server.py # Three-tier MCP server
├── formats/         # Content negotiation (JSON, Markdown, CSV, YAML)
└── utils/           # Shared utilities (yaml, markdown)

Entry Points

Imports flow cli/server → services → storage; storage never imports services. The allowed surface-to-storage exceptions are a ratchet whose count can only fall, in test_layer_boundaries.py. The inner-layer rule is enforced by test_storage_never_imports_services.py; the migrated CLI surfaces are covered by test_cli_surfaces_through_services.py. For public error text, follow the API standard, enforced by test_public_message_logged_once.py.

Command Module Purpose
pyrite pyrite.cli:main Full CLI (Typer) — primary interface for humans and agents
pyrite-read pyrite.read_cli:main Read-only CLI (safe for untrusted agents)
pyrite-admin pyrite.admin_cli:main Admin CLI (DB management, config)
pyrite-server pyrite.server.api:main REST API + web UI server

Key Principles

  1. Service Layer: Business logic lives in services/, not in CLI/API/MCP handlers
  2. Repository Pattern: File operations go through KBRepository
  3. Two-Tier Durability: Markdown files (git) = source of truth, SQLite/Postgres = derived index
  4. Plugin Protocol: Extensions use structural typing (Protocol) — no base class inheritance required
  5. SearchBackend Abstraction: All search operations go through SearchBackend protocol (SQLite or Postgres)

Running the tests

Pyrite is written largely by AI agents and runs on its users' machines, so most tests are medium: agents build units that pass alone and do not work together, and a user's machine is production, with no rollback. New behaviour, every fix and every guard is tested through the real wiring, so a guard's test fails when the guard is mis-wired, not only when its logic is wrong.

Size What For Runs
Small one process, no I/O pure logic with a large input space (parsers, schema validation, query sanitizing, selection rules), where medium is too slow to cover it editing, pre-push, PR CI
Medium (default) one machine, the real wiring: SQLite, temp dirs, TestClient, the CLI via Typer, MCP dispatch, git in temp repos, subprocesses new behaviour, fixes, guards editing, pre-push, PR CI
Large several processes or a browser the release gate, standing in for the production monitoring a hosted service would have: live server + MCP smoke, the tutorial, Playwright, install from the tag, upgrade on a real KB dev after merge, manual, release

scripts/test-affected picks tests by what a change can reach, not by size. Tests carry no size marker yet.

Everything

Measured gate snapshots are recorded in #1045 and the CI shard-report job. The #1045 groom records about 19,800 collected ids at 3e350972; its earlier 16,583-id gate recorded 1,240 seconds of 4-vCPU shard time. Use the shard report to refresh counts and timings as the suite changes.

scripts/heavy_lock.py -- .venv/bin/pytest tests/ extensions/ -n 4   # backend
cd web && npm ci && npm run check && npm run test:unit && npm run build   # frontend
HF_HUB_OFFLINE=1 .venv/bin/pytest tests/e2e -m e2e -n 4 --dist loadfile   # large: real server and MCP processes
PATH="$PWD/.venv/bin:$PATH" bash scripts/run_tutorial.sh                  # large: docs/getting-started.md as a test
PATH="$PWD/.venv/bin:$PATH" bash scripts/run_tutorial.sh docs/tutorials/pyrite-in-20-minutes.md   # large: the 20-minute tutorial as a test (clones the demo KBs)
cd web && npx playwright install chromium && cd .. && scripts/e2e.sh      # large: browser; manual-only in CI while non-deterministic

Use -n 4, not -n auto, on a laptop: -n auto starts a worker per core, each with its own databases and temp trees, and several worktrees doing that at once ran a 16 GB machine out of memory (#168) and filled its disk (#356).

One heavy run at a time per machine. scripts/test-affected --run (and so the pre-push hook), scripts/verify-red.sh and scripts/e2e.sh (and so npm run test:e2e) take one lock per user per machine, ~/.cache/pyrite/heavy.lock (scripts/heavy_lock.py), shared by every worktree. A second run waits its turn, in the order it arrived, and prints heavy-lock: waiting for the heavy-run lock ..., held by pid P (command) in <directory> since <time> on entry and every minute; it starts when the holder ends. Anything else heavy goes through the same lock with scripts/heavy_lock.py -- <command>, as in the commands above.

  • The lock covers the run's command, not just the wrapper: stopping the wrapper (Ctrl-C, kill, a closed terminal) passes the signal on and the lock is let go only when the command has ended. If the wrapper is SIGKILLed, the kernel frees the lock at once -- there is never a stale lock to delete -- and the next run waits, saying so, until the command that wrapper started has ended.
  • A lock it cannot use (an unwritable ~/.cache, a filesystem without flock) stops the run with a one-line error naming PYRITE_SUITE_LOCK_SKIP; where fcntl does not exist (Windows) runs go ahead without the lock and say so.
  • PYRITE_SUITE_LOCK_SKIP=1 runs without it (a run you know is small, a machine that can afford two). A single test file through plain pytest takes no lock.
  • PYRITE_SUITE_LOCK_TIMEOUT (seconds, default 3600) bounds the wait; when it runs out the command is not run and the exit status is 75. PYRITE_SUITE_LOCK moves the lock file (tests use a temporary one).
  • CI takes no lock (CI or GITHUB_ACTIONS set).

A subset

.venv/bin/pytest tests/test_storage.py -n 4                         # one file
.venv/bin/pytest tests/test_storage.py -k search                    # matching tests
.venv/bin/pytest "tests/test_rest_api.py::TestKBEndpoints::test_list_kbs"   # one test
.venv/bin/pytest extensions/software-kb -n 4                        # one extension
.venv/bin/pytest tests/ extensions/ -m core -n 4                    # the core smoke set
scripts/test-affected --list          # what your branch affects, against origin/dev's merge base
scripts/test-affected --explain       # ... and why each test was chosen
scripts/test-affected --run           # run it: core + affected, -n 4 (-n N or -n auto)

test-affected diffs your working tree, uncommitted and untracked files included, against the merge base with --base (default origin/dev; --committed ignores uncommitted work). It selects every test that imports, through any chain, a module you changed or uses a conftest fixture that does, plus the tests that load plugins when an extension changes, plus the core set; and it switches to the full suite when you touch conftest.py, pyproject.toml, pytest or hook configuration, CI workflows or tests/**/fixtures/. Its known limit is import-time reach: importing pkg.x runs pkg/__init__.py, which it does not follow, so a change to pyrite/services/kb_service.py selects 167 of the 281 test files that execute it on import. CI catches the rest.

CLI output is rendered the same everywhere. tests/conftest.py pins the rendering environment before any CLI module is imported: ambient FORCE_COLOR, PY_COLORS, NO_COLOR and TTY_COMPATIBLE are removed, COLUMNS and TERMINAL_WIDTH are 80, TERM is xterm-256color, and _TYPER_FORCE_DISABLE_TERMINAL is set. The last matters most: Typer renders help as ANSI in any process where GITHUB_ACTIONS is set (usage errors no longer are Typer's to render: the root answers them as a JSON document, #303), which is why a test could pass on a laptop and fail in CI (#884). A test that checks styling on purpose takes the terminal_colour fixture (in-process Typer), Console(force_terminal=True), or FORCE_COLOR=1 in a subprocess's env. tests/test_cli_output_is_deterministic.py runs the CLI under the CI variables to catch a regression.

Experimental tests (#657). A red required check means the core broke. Tests of the surfaces kb/designs/alpha-supported-surface.md calls experimental (the extensions, tasks, REST and the web UI, /ws, the AI endpoints, MCP prompts and resources and the non-core tools, Postgres, the overlay backend and worktrees, the repo/auth/extension/export/ collections CLI groups) carry the experimental marker. Nobody writes it by hand: tests/experimental_surface.py maps paths and node ids to surfaces, and the root conftest.py applies it. Security properties (authorization, read scoping, containment of paths, credential handling, the characterization oracle, escaping) are never experimental, whatever surface they go through; the same file lists them, and a test checks the mapping against a real collection. The gate decides, not a test's name: an experimental test whose body touches that vocabulary (paths leaving a root, private or readable sets, read-only, redaction, credentials, escaping, tiers) fails tests/test_experimental_surface.py until it is listed as security (NEVER_EXPERIMENTAL) or reviewed with a reason (REVIEWED_EXPERIMENTAL).

scripts/test-affected --run --full             # the core, as CI's gating job runs it (-m "not slow and not e2e and not experimental")
scripts/heavy_lock.py -- .venv/bin/pytest tests/ extensions/ -n 4 -m "experimental and not slow and not e2e"   # the experimental set
scripts/test-affected --run --experimental      # the pre-push selection, experimental tests included

A plain pytest runs both. scripts/test-affected --run, and so the pre-push hook, runs the core only (PYRITE_PUSH_EXPERIMENTAL=1 or --experimental includes the rest). In CI the test job, which gate needs, runs the core; the experimental job runs the rest on every PR and on dev, does not block a merge, and is red only for news: a failure in neither tests/experimental_known_failures.txt nor an open experimental-broken issue, a PR that adds to that list (it can only shrink), or a run that did not complete. On dev each of those opens or updates an experimental-broken issue. A file that fails to import stops the core run only if it holds a core or security case; one whose tests are all experimental is a warning there and a failure in the experimental job. test-affected --run says how many experimental tests it left out. A new test of an experimental surface needs no marker if its path is mapped; a new file for one needs a line in tests/experimental_surface.py.

Each tree is tested once. A --run that passes on a clean tree (nothing uncommitted in tracked files, no untracked .py file, and no untracked or gitignored file under pyrite/, tests/, extensions/, kb/ or scripts/ beyond __pycache__-style build output), using the worktree's own .venv, records a stamp: the tree's SHA, the Python major.minor and the tests it ran, under the git common directory, so every worktree of the repository shares it. A later --run -- the pre-push hook's included, which looks up the tree of the ref being pushed -- whose tests the stamp covers prints already passed on tree <sha> (...); skipping and exits 0. A dirty tree is never stamped and never skips; failures are never stamped, and neither is a run with PYTEST_ADDOPTS or PYTEST_PLUGINS set; --force or PYRITE_PUSH_FORCE=1 ignores stamps. Stamps older than 14 days are ignored and pruned. A stamp is keyed on the tree and the Python version, not the environment: a pass where the Postgres tests skipped (PYRITE_TEST_PG_URL unset) covers a later run where it is set. When what changed is the environment, use --force.

A verified commit is not tested again at the push. A commit is verified when the required check (gate) is green on that exact SHA on GitHub. That rule lives in one place, scripts/verified_commit.py, and scripts/release.py and the pre-push hook both use it. When the tip of the ref you push is verified, the hook prints <sha> is verified (gate=success, gate=success on <owner>/<repo>); not re-running the local suite and exits 0 (one gate= per workflow run that tested the commit: a dev tip has two, the merge queue's and the push's). You will meet this when you push a commit GitHub has already tested to another branch; the release's push of dev's tip to main is the usual case. An ordinary push of new commits is unaffected and makes no request: GitHub cannot have tested a commit it has not been sent.

The lookup fails closed. If gh is missing or not logged in, the network is down, the request takes more than 8 seconds, the API errors, the check is pending, red, renamed or absent, or the answer is not one the script understands, the commit is not verified and the hook runs the tests as it always has. Only the pushed tip is asked about: a verified commit says nothing for commits on top of it. The check must be named exactly gate, come from GitHub Actions, and conclude success (skipped does not count) in every workflow run that tested the SHA.

What that is evidence of: CI accepted the commit. Every job gate needs succeeded or was skipped by CI's change classifier: Python 3.13 in the merge queue and 3.11 and 3.12 on the push to dev that follows, one interpreter (with test skipped on a docs-only change) on a pull request. It does not say a particular selection of tests ran. So PYRITE_PUSH_FULL=1 still runs the full suite, PYRITE_PUSH_EXPERIMENTAL=1 still runs (gate does not need the experimental job), and --force or PYRITE_PUSH_FORCE=1 runs the tests whatever CI said. git push of several refs at once is examined by pre-commit for its first ref only, as before.

After a failure that looks load-caused (a timeout, a flaky port), re-run only what failed rather than the whole selection:

scripts/test-affected --run -- --lf    # anything after -- goes to pytest

A --lf pass is not stamped, since only part of the selection ran; when it is green, the next full --run (or the push) runs the selection once more and stamps it.

When to test what

When Run
While editing the test file you are changing; scripts/test-affected --run
Before a commit nothing extra: the commit hooks run ruff and the fast checks in seconds
Before a push the pre-push hook runs scripts/test-affected --run on PYRITE_PUSH_WORKERS (default 4) workers, unless your own --run already passed on the tree being pushed (see Each tree is tested once above) or the commit being pushed is already verified by CI (see A verified commit is not tested again at the push). It already runs everything for conftest, fixtures, pyproject and config changes; set PYRITE_PUSH_FULL=1 yourself for storage or migration changes and cross-cutting refactors
On the pull request nothing: CI runs the backend suite on one interpreter (a failure is the first thing in its log; the 25 slowest tests go to the step summary and a junit artifact is kept 30 days; mypy is its own advisory job: it fails only when a file has more type errors than the change's base commit (a PR's merge-ref parent, a push's previous tip; .mypy-baseline.json is the fallback when there is none), and after you fix errors you lower the baseline with mypy pyrite/ --ignore-missing-imports > mypy.out; python scripts/mypy_ratchet.py mypy.out --update); the backend suite runs as 3 parallel shards per interpreter balanced by .test_durations.gz, and shard-report proves they ran every test once) (all three Pythons when test infrastructure changes), KB validation, the frontend job when web/ changes, the advisory verify-red job (your new tests, without and with your change, graded against the merge commit's first parent; it is not in gate and never blocks a merge, and CI does not pass it --enforce-fix; its claim rule handles module-level tables on the test function itself, grades the whole function for an inline parametrize list, and selects nothing for class-level, fixture-params, generate-hook and imported tables; a control counts only when written on the test or one of its parameters, and one added another way (class or module pytestmark, a hook, a fixture, the test body) turns the job red; it runs on pull requests, not in the merge queue, and CI's environment, which has no Postgres, is the one it reports in; gating waits for #1104's model; see docs/testing.md) and diff coverage; the merge queue runs the full three-Python matrix on the exact commit about to land (#400); the push to dev after the merge runs the e2e smoke and the tutorial, and the matrix and frontend again only if the queue did not already pass that SHA
A frontend change cd web && npm run check && npm run test:unit && npm run build
A release first the rehearsal: scripts/release.py <version> (a dry run) runs every check and names each one that would stop --execute on this machine -- untracked files, the changelog section's date, the branch, whether the commit is verified, whether the private fixes repository (the security remote; --private-remote, or --no-private-remote for a project that keeps none) holds a change dev lacks, and what the pre-push hook will do for the pushes. Then the large tests: scripts/release.py installs the release commit into a fresh venv and runs the tutorial against it; Playwright and the smoke layer per the release runbook

What CI guarantees: no pull request merges until the full backend suite has passed on top of current dev. Run the full suite locally to reproduce a CI failure, not out of habit.

The suite does not load the embedding model unless a test is marked @pytest.mark.embeddings; everything else runs with auto_embed off. A test that passes alone but fails under -n auto is a bug in that test (shared state, a fixed wall-clock timeout, an unclosed database), not a reason to run serially — tests/test_task_claim_concurrency.py shows the pattern for process-spawning tests.

The runner itself is pinned. pytest, pytest-cov and pytest-xdist are exact == pins in the dev extra (#128) — not a floor like the rest of the project's dependencies — so every worktree venv and every CI leg run the identical version. An unbounded pytest>=8.0.0 once resolved 9.1.1 on one interpreter and 9.0.2 on another; a change that passed the PR gate under one version broke dev under the other. tests/test_dev_process_config.py asserts the pins stay exact, so loosening one is a visible diff, not a silent drift on the next uv pip install. The same is now true of every other dependency through uv.lock (see The dependency lock); the runner's exact pins remain because they are also what pyproject.toml tells a contributor who installs without the lock. After changing a pin, run scripts/lock-deps.sh, then refresh your worktree's venv and confirm it took:

uv pip install --python .venv/bin/python -c "$(scripts/lock-constraints.sh)" -e ".[all,dev]"
.venv/bin/python -m pytest --version

Writing Tests

Guards

A guard is a test that reads the test sources and fails on a pattern. It is marked @pytest.mark.guard (on the function, not the module), and scripts/test-affected selects it whenever a changed path is under tests/ or extensions/*/tests/, a deleted test file included, so the pre-push run tells you before CI does. A source-only change selects none of them. See why with scripts/test-affected --explain.

Guard Fails when a test What to change
test_no_test_mocks_the_service_behind_the_entry_point_it_drives and test_the_allowlist_matches_the_tree_exactly (tests/test_tests_drive_the_surface_not_the_mock.py) patches a service behind the entry point it drives; or ALLOWLIST (path -> patch count, why) differs from the tree in any file or in size, in either direction seed the world instead of patching; after removing patches, lower that file's count and ALLOWLIST_SIZE; never raise either
test_no_test_call_can_wait_forever and test_cheap_bcrypt_patch_lives_only_in_the_root_conftest (tests/test_test_rules.py) makes a blocking call with no deadline; or sets the test bcrypt cost outside the root conftest give the call a timeout=; keep the cost switch in conftest.py
TestSecurityVocabularyNeedsAReason (tests/test_experimental_surface.py) is mapped experimental yet touches the security vocabulary, or a reviewed entry no longer matches list it in NEVER_EXPERIMENTAL, or in REVIEWED_EXPERIMENTAL with the reason it is not a security test; delete a stale entry
test_cli_help_assertions_are_plain (tests/test_cli_help_assertions_are_plain.py) checks a CLI flag against raw help output wrap it in tests.cli_help.plain()
TestNoTestReadsAFragmentByName (tests/test_changelog_fragments.py) reads a changelog.d/ fragment by name fragments are deleted at release; build the text in the test
test_no_file_adds_a_site, test_a_file_that_shrank_lowers_its_line and test_the_baseline_only_comes_down_from_the_merge_base (tests/test_production_wiring_guard.py) overrides get_db in dependency_overrides or patches load_config more than tests/production_wiring_baseline.txt allows for that file; or a file dropped below its line; or a baseline line is added or raised against the merge base with origin/dev use the world (make_client, rest_api_env, cli_world, tests/_world.py); after removing sites, lower or remove that file's line; never raise one

Adding a guard: mark each scanning function @pytest.mark.guard, add its row here, and keep it cheap (these run on every push that touches a test).

Regenerating goldens

Characterization goldens (tests/characterization/goldens/) pin the response contracts for REST, MCP, and error bodies across all principals. Gating tests compare against these files; they are never regenerated in CI.

A migration PR may not change a golden (ADR-0037). When an intentional behavior change updates responses:

PYRITE_CHARACTERIZATION_REGENERATE=1 .venv/bin/pytest tests/characterization/

Run the regenerate serially without -n. golden_io.py refuses regeneration under pytest-xdist because each worker records only the goldens its own tests observed (#712, fixed by #1225). The per-principal file lock does not make parallel regeneration supported. Review git diff tests/characterization/goldens/ carefully before committing.

Branches, hooks and pull requests

Branches (ADR-0025 and ADR-0032):

  • dev is the default branch and where work integrates. main is releases only and moves by fast-forward to a commit that already passed CI.
  • Branch from dev, open the PR against dev. Name the branch for what it holds: fix/*, feature/*, docs/*, kb/* (KB entries only) or process/* (tooling and workflow). Never push to dev. Rebase is the default merge method (it keeps your commits and their messages); squash is fine for a branch whose history is noise.
  • A PR merges when its checks are green on top of current dev — one required check, gate, summarizes the Python suite, the frontend build and KB validation (whichever the change needs), and the branch must be up to date. If dev is broken, nothing merges until it is fixed. A PR goes BEHIND the moment another one merges; bring it up to date with gh pr update-branch <N> --rebase (auto-merge does not do it for you).
  • A PR is a unit a reviewer can hold in their head: complete on one theme, as many commits as the idea needs, never a fragment of a larger thing. A follow-up to work already in review goes onto that PR's branch, not into a new PR.

Git hooks — pre-commit install installs all three:

Stage Runs Takes
commit ruff, formatting, file hygiene, import-cycle check, KB schema validation seconds
commit-msg a fix: commit must touch tests/ —
pre-push scripts/test-affected --run: core + affected tests on PYRITE_PUSH_WORKERS (default 4) workers, only when the push touches code, tests, scripts or test config (a docs- or KB-only push skips it); skipped when the pushed tree already passed here or the pushed tip is verified by CI; PYRITE_PUSH_FULL=1 runs the full suite Seconds to minutes, depending on what changed

If pre-commit install refuses with "Cowardly refusing to install hooks with core.hooksPath set", run git config --unset-all core.hooksPath first; some environments point it at a directory of unused .sample files. If ruff-format reformats files, the commit stops: re-stage and commit again.

The commit stage stays fast on purpose: pre-commit stashes every unstaged edit in the working tree to ~/.cache/pre-commit/patch* while the commit hooks run, so a slow hook makes edits vanish for the minutes it takes, and there is deliberately no pytest at commit. tests/test_dev_process_config.py pins this layout; change the config and the tests together. If a commit is killed mid-hook, unstaged edits may exist only in the newest patch file: git apply --check ~/.cache/pre-commit/patch<newest>, then git apply it.

The hook trigger uses a three-dot diff; scripts/test-affected selects from the two-dot pushed range. A history-only force-push can trigger a core-only run. pre-commit checks the first non-deletion ref of a multi-ref push only; push one branch at a time when relying on the local hook. CI remains the gate.

CI runs the same checks plus the full Python matrix, Postgres, the frontend build (Playwright runs only by hand, via workflow_dispatch; run scripts/e2e.sh locally for a web/ change), so the pre-push run does not have to be perfect. If it fails in a test your change does not touch, re-run that test alone (scripts/test-affected --run -- --lf); if it passes, push with --no-verify and say so in the PR, and CI will decide. Name the test in the PR; if CI fails it too, it is a real failure your change caused, even in a test you did not touch. A failure in a test your change touches is a real failure: fix it. File an issue for a flaky test only if it fails that way again.

Claiming an issue: before you spend more than an hour on an issue, say so on the issue: two or three lines on how you'll fix it and what test proves it. A draft PR with that in the body is even better — we'll steer you there before you write much, and the draft is visible to everyone else looking at the issue. The plan scales with the change: for a good first issue one sentence is enough ("I'll add id/kb_name to the three projections and a test per command").

A claim with no PR after 5 days lapses. Two people on one issue is fine — the first PR that meets the acceptance criteria merges, and we credit the other in the changelog entry for the change.

A placeholder commit or file is not a claim, and we don't merge placeholders.

Push as you go. A fix that exists only on your machine cannot be reviewed, and "it's in a local commit" has cost a round trip more than once.

Pull requests:

  1. git checkout -b fix/what-it-fixes dev (or feature/...), ideally in its own worktree (scripts/new-worktree.sh fix/what-it-fixes): one branch, one worktree, so parallel work never shares a tree. A worktree is required when several sessions or agents work in one clone at once; a single session on a plain clone is fine.
  2. Write the failing test, then the fix. Commit each passing step.
  3. Push; the pre-push hook runs the affected tests (CI runs the full suite)
  4. Open the PR against dev and fill in the template (Fixes #N for bugs). Open it as a draft right after your first push so CI starts; mark it ready when you think it is done. From a fork, name the upstream: gh pr create --repo pyrite-wiki/pyrite --base dev --draft. Review and merge are the maintainer's; you do not arm auto-merge. See "From a fork" below.
  5. Expect a first response within 72 hours. If you have heard nothing after that, comment on the PR — it is a lapse, not a verdict, and saying so is doing us a favour.

From a fork: scripts/new-worktree.sh, scripts/test-affected and scripts/verify-red.sh all read origin/dev, so origin must be the upstream repo, not your fork (after gh repo fork --remote, origin/dev is your fork's stale dev). Clone upstream and add the fork as a second remote:

git clone https://github.com/pyrite-wiki/pyrite.git && cd pyrite
git remote add fork https://github.com/<you>/pyrite.git
# ... work on a branch ...
git push -u fork <branch>
gh pr create --repo pyrite-wiki/pyrite --base dev --draft

Stage explicit paths (git add <file>), never git add -A, git add -u or git add .: they sweep in edits you did not mean to commit, including a sub-agent's.

Commit messages use conventional commits (feat:, fix:, docs:, test:, refactor:, ci:, kb:).

Maintainer-only landing with a merge commit

Ordinary contributor PRs use the configured merge method. A maintainer who needs a merge commit for a landing branch must coordinate three independent settings (#1036); green checks and MERGEABLE alone do not prove the queue can use that method:

  1. Repository Settings → General → Pull Requests → Allow merge commits.
  2. The dev ruleset's Require merge queue → Merge method.
  3. The same ruleset's Require a pull request → Allowed merge methods.

Before changing anything, record all three original values and the queue's full parameters, particularly max_entries_to_merge, min_entries_to_merge and its wait timeout. Use the repository's ruleset settings or a read-only snapshot (replace the ID with the dev ruleset's ID):

gh api repos/pyrite-wiki/pyrite/rulesets
gh api repos/pyrite-wiki/pyrite/rulesets/<dev-ruleset-id> > dev-ruleset-before.json

The repository-level permission is separate from that ruleset snapshot; record it too. If the maintainer approves a temporary merge-commit landing, enable it at all three gates, then use the normal PR and CI queue. This is not permission to bypass checks or push directly to dev.

After the landing, restore the recorded pre-change values, including every queue parameter, and read the settings back. Do not take a new snapshot of the temporary state as the restoration source. In the #1036 incident, restoring max_entries_to_merge: 0 and min_entries_to_merge: 2 held a green PR for 30 minutes; the cited normal values were max 5, min 1. Prefer the actual pre-change snapshot over assuming those values forever. If a green PR stalls, inspect all three merge-method gates and these group-size parameters before rerunning CI or changing the PR.

Where work is tracked

Two places, one rule — an item lives in exactly one of them (ADR-0033):

  • Bugs and requests → GitHub Issues. Anyone can file one; use the templates. Issues labelled good first issue are small, well-specified and a fine place to start.

  • The roadmap → kb/ in this repo: epics, planned work and architecture decisions, browsable with the tool itself:

    pyrite sw backlog        # planned work, by priority
    pyrite sw adrs           # architecture decision records
    pyrite sw components     # module documentation

    kb/roadmap.md is the plan for the next releases. A request we accept gets a roadmap item that links back to the issue.

Contributing a fix. The PRs that merge fastest here look like this — and the ones that arrived on 2026-09-18 from four first-time contributors all did:

  • One issue per PR, and the diff stays inside it. A stray hunk from another project (an editor's .gitignore additions, say) is the most common thing a review asks to remove.

  • A test that fails without the fix. CI checks it for you: the advisory verify-red job checks out the merge base in a throwaway tree, adds your test files, runs the tests you added or edited, then adds the rest of your change and runs them again. Its summary line, e.g. verify-red: 3 red · 0 import-only · 1 unexpected pass · 0 n/a, is on the run's summary page, with a row for each test that is not red. red is what a review wants to see. import-only is weaker: the test fails only because a name your change adds is missing, which shows it needs your code, not that it checks what the code does. unexpected pass leaves a warning on the test: it does not exercise the change. If it is a deliberate "this still works" guard, mark it @pytest.mark.control(reason="...") and it counts as a control instead. n/a means no claim (it skipped, failed with the fix, or timed out). scripts/verify-red.sh runs the same check locally; it never modifies your checkout, and it includes uncommitted work.

  • Diff coverage: on a pull request the 3.12 test run measures coverage, and diff-cover lists the lines you changed that no test runs (target 80%). Like verify-red it is advisory for now; see docs/testing.md.

  • The affected tests green locally (scripts/test-affected --run), plus ruff check and ruff format --check. CI runs the full suite on the PR.

  • A changelog fragment: a new file changelog.d/<slug>.<section>.md containing the bullet as it should read in the release notes. Do not edit CHANGELOG.md — it is the one file every pull request used to conflict on, and a fragment has a name nobody else picks, so two branches in flight cannot collide. changelog.d/README.md lists the sections and shows an example; the release script assembles the fragments when the release is cut.

    If your change touches pyrite/ or extensions/ and adds no fragment, CI leaves a warning on the pull request. It is a reminder, not a gate — nothing is blocked, and no one has to argue with a script about whether a change is user-visible. When it genuinely isn't one (a refactor with no behaviour change), say so in the pull-request description and the warning goes away:

    Changelog: none
    
  • AI-assisted contributions are welcome here. If an AI coding agent wrote or co-wrote your change, declare it with a Co-authored-by: trailer on the commit (most agent tools add this automatically) — it is machine-readable, it survives a squash-merge, and it is the form we'll look for first. A mention in the PR body is welcome too, and helps the reviewer know what to look at first, but it's optional on top of the trailer, not instead of it.

What happens next: an outside PR is reviewed ahead of the maintainer's own work, and the review is posted as a comment with a plain recommendation (merge as is, merge after listed changes, or which of two competing PRs and what to credit from the other). In practice that has often been within the hour, but the hour is a happy accident of when you caught us — this is one maintainer in one timezone who sleeps. 72 hours is the limit, and it is borrowed from the Apache Way: there, a proposal that draws no objection in 72 hours is taken as having consent, on the principle that silence must have a deadline or it becomes a veto. Here the same clock runs the other direction — it bounds how long you should have to wait for an answer, rather than how long we may wait for one. Past 72 hours, ping the PR.

First-time contributors' CI runs wait for a maintainer to approve them; that is a GitHub safety default, not a judgement. A maintainer may rebase your branch or push one small, credited fixup commit to it with a comment saying what changed — your commits and authorship stay yours. The merge itself is the maintainer's click.

Security issues: never in a public issue — see SECURITY.md.

Private material: this repository and its KB are public. Placeholders, not names, for anything that is not yours to publish; no absolute home paths.

Project Configuration

  • KB config: kb.yaml in each KB directory
  • AI agents: start at AGENTS.md; Claude Code users also get the pyrite-dev skill (.claude/skills/pyrite-dev/SKILL.md), which adds a method (tests first, evidence, a report) and links back here for every command
  • Plugin developer guide: kb/notes/plugin-developer-guide.md
  • Architecture docs: kb/components/ and kb/adrs/

Getting Help

  • A bug or a feature request: open an issue
  • A question about how something works: open an issue with the question label
  • Something you found by deploying it: that is the most valuable report there is — see the v0.24.1 notes for the three that shaped that release

Contributors

Maintainer: Mark Ramm (BDFL; see ADR-0032). Contributors are credited by name in the release notes of the release their work ships in (the runbook lists every outside author of a merged PR), in the changelog entry for the change, and in the README.

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Refresh the fallback type baseline before a release

Before preparing the release commit, run the same pinned mypy environment as CI, then lower its no-base fallback (issue#1103):

mypy pyrite/ --ignore-missing-imports > mypy-release.out || true
python scripts/mypy_ratchet.py mypy-release.out --update

Review and include the resulting .mypy-baseline.json in the release PR. A crash or any per-file rise refuses the update: fix those errors instead of using --allow-increase. Normal PR/push runs still compare with their actual base commit, so refreshing this fallback never hides a regression in a PR.