Skip to content

Contribute to the project

Use this guide to set up a development environment, run the check suite, submit a pull request, and keep documentation in sync with code changes.

Set up a development environment

  1. Clone the repository:
git clone https://github.com/eman/quilt-hp-python.git
cd quilt-hp-python
  1. Create a virtual environment and install all dev dependencies:
python3 -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e ".[dev,cli,docs]"

dev installs the test, lint and type-check tools (pytest, pytest-asyncio, pytest-textual-snapshot, time-machine, mypy, ruff). cli installs the CLI and TUI dependencies the tests exercise, and docs installs MkDocs.

Run the full check suite

Before opening a pull request, all of these checks must pass:

# Linter and formatter
ruff check src/ tests/
ruff format --check src/ tests/

# Type checker
mypy src/

# Tests
pytest

# Docs build (strict mode — catches broken links)
python3 scripts/check_docs_nav.py
python3 -m mkdocs build --strict -q

Run them in this order. Fix linter and type errors before running tests, and run check_docs_nav.py before the docs build to get clearer error messages.

TUI snapshot tests

tests/test_tui_snapshots.py renders every TUI screen at 100×30 and 160×45 and compares it with the SVGs in tests/__snapshots__/. The screens are rendered offline from tests/fixtures/system_snapshot.bin, a scrubbed capture of a real system, with the clock frozen, so the output is identical on every machine.

After an intended visual change, regenerate the snapshots and review them before committing:

pytest tests/test_tui_snapshots.py --snapshot-update

A failing run writes snapshot_report.html, which shows each differing screen side by side.

Some of these snapshots are also the screenshots in Use the terminal UI. After updating snapshots, refresh them with python scripts/update_tui_screenshots.py; tests/test_tui_screenshots.py fails while they differ.

Submit a pull request

  1. Create a branch from main:
git checkout -b feature/my-change

  1. Make your changes. Add or update tests as appropriate.

  2. Run the full check suite (see above). All four checks must pass.

  3. Commit with a descriptive message (present-tense imperative, under 72 characters):

Add support for DeclaredUserType in patch_user_attributes
Fix token expiry buffer calculation
  1. Push and open a pull request against main. Describe what changed and why.

All PRs require at least one passing CI run before merging. The CI runs the same five commands listed above.

Update docs when source code changes

When you change src/quilt_hp/, update the corresponding reference documentation in the same pull request:

Source change Documentation to update
New or changed QuiltClient method docs/reference/client.md
New or changed model field docs/reference/models.md
New or changed token protocol docs/reference/token-management.md
New or changed service class docs/reference/models.md
Changed exception type or message docs/reference/client.md
New or changed HDS entity semantic docs/reference/hds-entities.md
Changed wrapped RPC coverage docs/reference/grpc-services-matrix.md

Stale documentation is a maintenance hazard. Reviewers will check that docs reflect the code.

Update docs when proto definitions change

When you change a .proto file in proto/cleaned/:

  1. Edit the proto file.

  2. Regenerate the stubs:

./scripts/regen_protos.sh

For detailed steps and troubleshooting, see Regenerate protobuf stubs.

  1. Update the service wrapper in src/quilt_hp/services/ for any new or changed RPC.

  2. Update QuiltClient in src/quilt_hp/client.py if the change is exposed publicly.

  3. Update documentation:

Proto change Documentation to update
New RPC method docs/reference/grpc-services-matrix.md
Removed RPC method docs/reference/grpc-services-matrix.md + docs/reference/client.md
New proto file / service docs/explanation/grpc-and-protobuf.md, docs/reference/grpc-services-matrix.md
Changed message fields docs/reference/hds-entities.md or docs/reference/models.md
  1. Run all checks:
ruff check src/
mypy src/
pytest
python3 scripts/check_docs_nav.py
python3 -m mkdocs build --strict -q
  1. Commit proto changes, regenerated stubs, source changes, and doc updates together in one pull request.