Skip to content

Development Guide

Jump to bottom
WilliM233 edited this page Mar 29, 2026 · 1 revision

Development Guide

A summary of how development works on BRAIN 3.0. This page covers the workflow, conventions, and key references. For the full developer setup (from clone to running API), see docs/dev-setup.md. For the authoritative coding standards and project structure, see CLAUDE.md.

Git Workflow

Branching Strategy

main          ← production deploys only
  └── develop ← integration branch, all features merge here
        └── feature/TICKET-XX-short-description
  • Never commit directly to main or develop
  • One branch per ticket, branched from develop
  • PRs target develop
  • main is updated from develop only for deployment milestones

Branch Naming

  • Features: feature/TICKET-XX-short-description
  • Documentation: docs/short-description

Commit Messages

Conventional Commits with ticket reference:

type(scope): description (#XX)

Types: feat, fix, docs, test, chore, refactor

Examples:

feat(api): add domain CRUD endpoints (#4)
fix(db): correct cascade delete on projects (#5)
docs: rewrite README with architecture overview
test(api): add composable filter tests for tasks (#5)

Commits should be atomic — one logical change per commit.

Pull Request Process

  1. Ensure all tests pass (pytest -v) and lint is clean (ruff check .)
  2. Push your feature branch and open a PR targeting develop
  3. Title format: TICKET-XX: Short description
  4. Fill out every section of the PR template:
Section What Goes There
Summary What was built, in plain language
Changes Files created/modified and why
How to Verify Step-by-step verification instructions
Deviations Anything that differs from the ticket spec (or "None")
Test Results Confirmation that tests pass, with output
Acceptance Checklist Criteria from the ticket, checked off

The Deviations section matters. If you deviated from the spec — even for good reasons — document it. Undocumented deviations create confusion during review.

Ticket Workflow

Work is organized through GitHub issues with detailed ticket specs in docs/tickets/.

  1. Read the ticket spec before starting work
  2. Create a feature branch from develop
  3. If anything in the ticket is ambiguous, ask — don't guess
  4. If you find a bug or issue outside the current ticket's scope, file a GitHub issue rather than fixing it inline
  5. Open a PR when complete, linking to the issue with Closes #XX

Testing

Tests use an in-memory SQLite database — no external dependencies needed.

pytest -v              # Full suite
pytest tests/test_tasks.py -v   # Single file
ruff check .           # Lint

CI runs both on every push and PR to develop. Both must pass.

Testing Standards

  • Every API endpoint gets: happy path, validation, not found (404), and filter tests
  • Tests must be independent — each creates its own data
  • Use the helper fixtures in tests/conftest.py (make_domain, make_goal, make_task, etc.)

Code Standards

Standard Rule
Style PEP 8
Type hints Required on all function signatures
Line length 100 characters max
Strings f-strings over .format() or %
Paths pathlib over os.path
ORM style SQLAlchemy 2.0 (DeclarativeBase, Mapped, mapped_column)
Schemas Pydantic 2.x with model_config = {"from_attributes": True}

Key References

Resource What It Covers
CLAUDE.md Full developer guide — project structure, conventions, design decisions
docs/dev-setup.md Prerequisites, clone, configure, start, test, troubleshoot
docs/deployment.md Production deployment on TrueNAS
docs/environment-variables.md Every env var documented
System Design Document Architecture, data model, schema, design philosophy

Clone this wiki locally