How We Ship | Handbook

We ship weekly. That's the default. The exceptions (hotfixes, critical rollouts) are documented below.

The release cycle

We work in one-week sprints. At the end of each sprint, we release. This creates a forcing function: if something isn't ready by end of sprint, it goes in the next one. No endless "almost done" states.

Monday–Thursday: Build. Open pull requests early, get review, iterate.
Friday: Cut the release. Final checks, deployment, brief team sync on what went out.

Sprint planning happens at the start of Monday. We review what shipped, confirm what we're working on this week, and surface any blockers.

Opening a pull request

Keep PRs focused. One thing per PR if possible. Large PRs are harder to review and harder to roll back.
Write a description that explains what changed and why, not just what. "Fixed bug in webhook handler" is worse than "Webhook handler was discarding events when the destination returned a 202. Changed to treat 202 as success."
Tag the reviewer directly. Don't assume someone will notice a PR in the queue.
Include testing instructions for anything non-obvious.

Code review

Every PR that touches production code needs at least one review before merging. The reviewer is looking for:

Correctness. Does this do what it says it does? Are there edge cases that break it?
Security. Any new attack surface? Any PII being logged or exposed?
Performance. Does this add latency to a hot path? Any N+1 queries?
Maintainability. Will the next person be able to understand what this does in six months?

Code review is not about personal style. Don't block PRs over formatting (use the linter for that) or variable naming preferences. Focus on things that actually matter.

If you disagree with a review comment, discuss it. Don't silently accept or silently ignore. The goal is the best code, not winning the argument.

Testing

We test the things that matter. That means:

Critical paths (event ingestion, destination delivery, consent pass-through) have automated tests
New features should have at least a smoke test before they ship
We don't block shipping on achieving perfect test coverage

Production is also a test environment. Ship, monitor, fix fast. This only works if we have alerts configured and someone is watching them.

Hotfixes

If something breaks in production, the process is:

Identify the issue and confirm the blast radius
Assign a P0 or P1 label in Linear (see Bug Prioritization)
Fix it, test it, ship it - don't wait for the next sprint
Notify affected customers if the issue was visible to them
Write a brief post-mortem for P0 issues within a week

Hotfixes skip the normal review process only when the fix is trivially obvious and the cost of waiting for review is greater than the risk. When in doubt, get a review.

Feature flags

We use feature flags to decouple deployment from release. This lets us:

Ship code to production before it's publicly available
Test with a subset of customers before a full rollout
Roll back a feature without a new deployment

Not every feature needs a flag. Small, low-risk changes can go straight to production. Bigger changes, API integrations, or anything with customer-visible impact should go behind a flag.

What gets monitored

Every new integration or service should have monitoring before it ships:

Error rate alerts
Latency alerts for latency-sensitive paths
Volume alerts for unexpectedly low activity (event ingestion drops, for example)

If something is in production but not monitored, we don't know when it breaks. That's not acceptable for infrastructure that customers depend on.

Deployment environments

Local: for development
Staging: for integration testing before production
Production: what customers use

Changes go local → staging → production. Never local → production directly, except for documentation or config changes that don't affect behavior.