Workflow

Owner: Engineering Last reviewed: 2026-Q2

Goal: Ship small, high-quality changes continuously with clear ownership.

Branching

• Trunk-based with short-lived feature branches from dev
• Keep PRs < 300 LOC effective diff when possible

Commit Messages

• Use type(scope): description.
• Common types: fix, feat, refactor, chore, docs, test, perf.
• Common scopes: backend, frontend, docs, infra.
• Keep the message one line, lowercase, and without a trailing period.

Definition of Ready

• Problem statement and scope agreed
• API/schemas drafted (if needed), OpenAPI impact known
• Success criteria and metrics identified

Implementation Steps

• Backend: route → schema → service → tests → OpenAPI
• Frontend: orval client regen → hook/api wrapper → UI → states → tests
• Security: authZ checks, input validation, file limits, secrets
• Observability: logs/traces around new paths; health if a new dependency

Reviews

• Request at least 1 reviewer FE/BE as relevant; include screenshots/GIFs or cURL for API
• Verify CI green and migrations safe

Merging & Deploy

• Squash merge to dev; pipelines build images and deploy to dev environment
• Validate smoke checks (health, basic flows)
• Promote to showcase with a short changelog; prod when enabled

Hotfixes

• Default path is still a small PR into dev, followed by deploy and validation.
• For urgent showcase/prod fixes, keep the patch minimal, record the risk and rollback, and back-merge the fix into dev immediately after deploy.
• Hotfixes touching auth, permissions, migrations, secrets, or infra still require a second review unless production mitigation cannot wait.

Post-merge

• Update handbook/ADRs if architecture changed
• Create follow-ups for leftovers; avoid scope creep in the current PR

Incident Handling

• Triage quickly; mitigate first, then root-cause
• Capture learnings in a short postmortem and create action items