Skip to content
SeedTrust Docs

Contribution Guidelines

Standards every developer follows when picking up a ticket, writing code, and closing it out.

GitHub CI Checks

Every PR targeting dev or main runs these checks automatically:

CheckWhat it does
Ruff linting & formattingRuns pre-commit with Ruff on all Python files. If issues are auto-fixable, the bot commits them directly — no action needed. If a check fails that can’t be auto-fixed, address it manually and push again.
Test suiteRuns uv run st run tests (Flask + FastAPI pytest suites). All tests must pass before merging.

You can run these locally before pushing:

Terminal window
uv run pre-commit run --all-files   # Ruff format + lint
uv run st run tests                 # Full test suite

Pull Requests

PRs don’t need to be exhaustive. A short description and a linked Jira ticket are enough.

What the PR needs:

  • PR type (feature, bug fix, refactor, etc.)
  • 2–3 sentence description of what changed and why
  • Link to the Jira ticket (ST-XXXX format)

What does NOT belong in the PR:

  • Detailed QA steps — those go in the Jira ticket (see Jira QA Sign-Off below)
  • Step-by-step test instructions — keep the PR lean

Documentation (Required)

After completing a feature or making a meaningful change to a module, update the relevant page in docs-site/src/content/docs/. If no page exists for the area you touched, create one.

Update or add docs when you:

  • Add new routes, endpoints, or workflows
  • Change existing behavior in a way a teammate would need to know about
  • Introduce a new module, model, or background job
  • Add a new operational procedure that warrants a runbook

Where things live:

TypeLocation
Module behaviordocs-site/src/content/docs/modules/
Operational proceduresdocs-site/src/content/docs/runbooks/
Architecture decisionsdocs-site/src/content/docs/adr/

Documentation changes should land in the same PR as the feature. Don’t leave them for a follow-up.

Unit Tests (Encouraged)

Unit tests are not required for every PR, but they are strongly encouraged — especially for:

  • Business logic (validation, calculations, state transitions)
  • ACH / financial processing code
  • Utility functions used across the codebase

See Getting Started for how to run the test suites.

Jira QA Sign-Off

Before moving a ticket to QA, leave a comment on the Jira ticket with:

  1. Modules touched — which areas of the codebase changed (e.g., Disbursement Requests, ACH Processing, Auth)
  2. Happy path tested by dev — a brief description of what you verified while building
  3. Risks or edge cases — anything QA should pay extra attention to (optional but helpful)

Example:

Modules touched: Disbursement Requests, Email Notifications

Dev happy path: Created a standard DR as an IP, submitted for CM review, confirmed CM received the review email and could approve. Tested with both ACH and check payment methods.

Watch out for: DR status display when the case has no active escrow agreement.

This gives QA the context they need without requiring a lengthy PR description.