Skip to main content

How We Work

The day-to-day engineering workflow — branches, Jira tickets, commits, reviews, and what "done" means. Read this before your first PR.

Branching: trunk-based​

We run trunk-based development across all repos.

feature/TI-XXX-*  ──short-lived (hours → ~1 day), WIP behind a feature flag──┐
                                                                             ▼
                                                 PR + required CI gates ──▶ master  (TRUNK)
                                                                             │
                                             every merge auto-deploys ──────┤──▶ DEV environment
                                                                             │
                                      release = tag vX.Y.Z on trunk ────────┴──▶ PRODUCTION
  • Trunk is master — the one long-lived branch in every repo. There is no develop or release branch.
  • Every merge to master auto-deploys to the dev environment (https://develop.theinterviews.ai). Dev is shared — keep trunk green.
  • Production promotion is a separate, deliberate step:
    • Backend services (Java API, video server, bot backend): push an annotated semver tag vX.Y.Z on a trunk commit — the tag triggers the prod deploy.
    • Frontends (main app, session room): fast-forward a thin production pointer branch to the chosen trunk commit — the hosting platform builds and serves from that branch. production is a deploy ref, not a parallel development line.
  • Work branches are short-lived and named for their ticket:
    • feature/TI-XXX-short-description — new functionality
    • fix/TI-XXX-short-description — bug fixes
    • chore/short-description — tooling, config, cleanup
  • Incomplete work still merges to trunk — behind a feature flag, default off. Flags live in platform config, so behavior can change without a redeploy. Don't sit on a long-running branch.
  • master is protected: changes land via PR with passing CI; no force-pushes, no branch deletion.

Tickets: everything traces to Jira​

  • Every task has a ticket (TI-XXX). If there isn't one, create it before you branch — the branch name needs the key anyway.

  • Smart commits — every commit message starts with the ticket key so commits, branches, and PRs link onto the ticket automatically:

    feat(TI-123): add recording consent banner
    fix(TI-456): handle empty resume upload

  • Status flows with the work: In Progress → In Review → QA/Testing → Done. Move the ticket yourself as the work moves; the ticket is the audit trail, not the chat.

  • Test instructions before QA handoff. Before a ticket goes to QA/Testing, write numbered step-by-step instructions in the ticket description: exact inputs and selections, the expected result per step, regression checks, rollback levers, and the concrete URLs to test on (local http://localhost:3000, dev https://develop.theinterviews.ai, prod https://www.theinterviews.ai, session room <SESSION_ROOM_URL>).

  • For significant milestones, post a comment on the ticket: what shipped, where, and the verification evidence.

The quality bar​

What "done" means here:

  • Tests ship with the feature. Unit/integration tests live in the owning repo and are green before commit. User-facing flows additionally get a Playwright browser spec in theinterviews-e2e, runnable against the dev build — every shipped behavior gets automated regression coverage.
  • Coverage at the highest meaningful level, not a vanity percentage. Test the behavior users depend on.
  • No silent failures. Don't swallow exceptions; fail loudly or handle deliberately. Optional integrations degrade gracefully, never crash.
  • One concern per PR. Don't mix a refactor into a feature, or cleanup into a bugfix. Keep diffs minimal.
  • Lint, types, and build green before commit — lint + typecheck + a passing build in the repo you touched. Fix the root cause; never bypass commit hooks.
  • No premature abstraction — extract at the second need, not the first. Comments explain surprising why, never what.
  • TODOs need a Jira ticket — no orphaned // TODO comments.
  • Verify against observed behavior, not assumption: run the thing once, confirm the output, then claim it works.

Review​

Two review gates, both human:

  1. Diff review before push. Read your own full diff before it leaves your machine — every change should be intentional and explainable.
  2. PR review before merge to trunk. All changes to master go through a pull request with at least one approval and passing CI. Reviewers look at correctness, blast radius, and rollback path — not just style.

Sensitive areas (billing, auth, database migrations) get extra scrutiny and are kept as their own small commits so they can be rolled back surgically. Migrations are reviewed with their rollback before anything is applied — and they're applied manually, never automatically.

How epics ship​

Stories and epics move on different cadences:

  • Stories land on dev incrementally. Each story merges to trunk complete (tests included) and auto-deploys to the dev environment, behind a feature flag where the work isn't ready for users.
  • Epics promote to production once, at the epic boundary — after the whole epic is built and tested on dev. We do not promote story-by-story to prod.
  • Commit cadence is story-wise. Phased checkpoints on your branch are fine; squash to one story-scoped commit at merge. Never collapse an entire epic into one commit, and never merge a half-finished story without a flag.
  • Prod promotion order: migrations first, then services, then frontends — with a stated rollback path per surface before promoting.
  • Human testing is reserved for critical, irreversible paths — live interview entry, billing, auth. Everything else is gated by automation, not manual QA.