Git Conventions
We use conventional commits (feat:, fix:, chore:) that generate changelogs automatically. Branches are named after tickets: feat/ZENO-123-add-heatmaps.
Commit messages should be imperative ("Add heatmaps" not "Added heatmaps") and explain why, not just what. The diff shows what changed—your message should explain the reasoning.
Pull Requests
Every change goes through code review. PRs should be small, focused, and include context for reviewers. We aim for reviews within 4 hours during working hours.
PR requirements:
- All tests pass
- Type checking succeeds
- At least one approval
- No unresolved comments
Good PR descriptions include: what changed, why it changed, how to test it, and any risks or follow-up work needed.
CI/CD Pipeline
Every push triggers our CI pipeline: lint, type check, test, build. Merges to main deploy to staging automatically. Production deploys require explicit approval.
The pipeline runs in under 5 minutes. If it takes longer, we treat that as a bug to fix. Fast feedback loops keep developers productive.
Environment Management
We maintain three environments:
- Development: Local machines with Wrangler for Workers and local Supabase.
- Staging: Production-like environment at staging subdomains. Used for final QA and demo.
- Production: The real thing. Deployed after staging verification and explicit approval.
Database Migrations
Schema changes go through Supabase migrations. Every migration must be reversible with a corresponding down migration. We test migrations on staging with production-like data before applying to production.
Release Process
We release continuously. Features go live as soon as they're ready, protected by feature flags. Major changes get announced in our changelog with clear migration guides.
Feature flags let us deploy code without enabling it for users. This means safer releases, gradual rollouts, and easy rollbacks if something goes wrong.