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.
- Python 3.11+ (3.13 recommended)
- Git
- uv (recommended) or pip
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 -qPytest prints the current collected and passed test counts in its summary; they change as the project and extensions grow.
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 staletests/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.
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 | bashIt 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:pg16container (the image, user, password and database CI uses, so a cloud pass predicts a CI pass) and exportsPYRITE_TEST_PG_URLonce it accepts connections. If Docker or the container fails, the session starts anyway with one warning and those tests skip. SetPYRITE_SETUP_POSTGRES=0in the environment's variables to opt out. Details:scripts/cloud-postgres.sh. - Embeddings are off by default:
sentence-transformerspulls torch; the tests that need it skip. For them, setPYRITE_SETUP_EXTRAS=all,postgresand addhuggingface.coto 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 ciinweb/when your change touches it. - Branches: the session's own branch is fine for a PR to
dev; name itfix/*orfeature/*if you create one yourself. One session is one checkout, so there is no worktree to make.
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.
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/- Use modern Python type hints (3.11+ syntax)
list[str]notList[str]str | NonenotOptional[str]dict[str, Any]notDict[str, Any]
- Use absolute imports within the package
- Group imports: stdlib, third-party, local
- Let ruff sort imports automatically
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)
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 |
- Service Layer: Business logic lives in
services/, not in CLI/API/MCP handlers - Repository Pattern: File operations go through
KBRepository - Two-Tier Durability: Markdown files (git) = source of truth, SQLite/Postgres = derived index
- Plugin Protocol: Extensions use structural typing (Protocol) — no base class inheritance required
- SearchBackend Abstraction: All search operations go through
SearchBackendprotocol (SQLite or Postgres)
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-deterministicUse -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 withoutflock) stops the run with a one-line error namingPYRITE_SUITE_LOCK_SKIP; wherefcntldoes not exist (Windows) runs go ahead without the lock and say so. PYRITE_SUITE_LOCK_SKIP=1runs without it (a run you know is small, a machine that can afford two). A single test file through plainpytesttakes 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_LOCKmoves the lock file (tests use a temporary one).- CI takes no lock (
CIorGITHUB_ACTIONSset).
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 includedA 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 pytestA --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-
Follow the deadline rule; test_test_rules.py enforces it.
-
Drive real services behind entry points; the mocking standard and test_tests_drive_the_surface_not_the_mock.py define the permitted edges.
-
Use the pinned CLI rendering environment, covered by test_cli_color_environment.py.
-
Tests live in
tests/; extension tests inextensions/<name>/tests/ -
Name test files
test_*.py -
A
fix:commit must include a test that fails without the fix (a hook checks that it touchestests/). A test-only commit followed by afix:commit fails the check: put the test in the same commit as the fix, or combine the commits if already separated (or use another prefix likerefactor:). -
Use pytest fixtures for common setup (
tmp_kb, isolated plugin registry); close anyPyriteDByou open -
Use
innotlenfor registry assertions (see testing standards)
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).
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 (ADR-0025 and ADR-0032):
devis the default branch and where work integrates.mainis releases only and moves by fast-forward to a commit that already passed CI.- Branch from
dev, open the PR againstdev. Name the branch for what it holds:fix/*,feature/*,docs/*,kb/*(KB entries only) orprocess/*(tooling and workflow). Never push todev. 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. Ifdevis broken, nothing merges until it is fixed. A PR goesBEHINDthe moment another one merges; bring it up to date withgh 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:
git checkout -b fix/what-it-fixes dev(orfeature/...), 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.- Write the failing test, then the fix. Commit each passing step.
- Push; the pre-push hook runs the affected tests (CI runs the full suite)
- Open the PR against
devand fill in the template (Fixes #Nfor 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. - 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 --draftStage 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:).
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:
- Repository Settings → General → Pull Requests → Allow merge commits.
- The
devruleset's Require merge queue → Merge method. - 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.jsonThe 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.
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 issueare 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.mdis 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
.gitignoreadditions, 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-redjob 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.shruns 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-coverlists the lines you changed that no test runs (target 80%). Likeverify-redit is advisory for now; see docs/testing.md. -
The affected tests green locally (
scripts/test-affected --run), plusruff checkandruff format --check. CI runs the full suite on the PR. -
A changelog fragment: a new file
changelog.d/<slug>.<section>.mdcontaining the bullet as it should read in the release notes. Do not editCHANGELOG.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.mdlists the sections and shows an example; the release script assembles the fragments when the release is cut.If your change touches
pyrite/orextensions/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.
- KB config:
kb.yamlin each KB directory - AI agents: start at AGENTS.md; Claude Code users also get the
pyrite-devskill (.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/andkb/adrs/
- A bug or a feature request: open an issue
- A question about how something works: open an issue with the
questionlabel - 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
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.
By contributing, you agree that your contributions will be licensed under the same license as the project.
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 --updateReview 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.