Branching and Git Workflow

Branching & Git Workflow

Flakemetry uses trunk-based development: main is always releasable, and all work happens on short-lived branches merged via pull request.

Branch model

main  ──●──────●──────●──────●───────►   (protected, always green, always releasable)
         \      \      \
          feat/  fix/   chore/           short-lived, one concern, deleted on merge

• main is protected — no direct pushes, no force-push, no deletion.
• Feature branches are short-lived (hours–days), scoped to one issue.
• Branches are squash-merged into main and auto-deleted.

Branch naming

<type>/<issue-number>-<short-kebab-summary>

Prefix	For
feat/	new capability
fix/	bug fix
chore/	tooling / maintenance
refactor/	internal change, no behaviour change
docs/	documentation / ADR
ci/	build / CI / release
spike/	throwaway exploration

Examples: feat/18-test-identity-engine, fix/57-scrub-jwt-in-stacktrace, ci/7-turbo-affected-pipeline.

Commit convention — Conventional Commits

<type>(<scope>): <summary>

feat(core): add L2 moved-file fingerprint matching
fix(api): reject oversized OTLP batches before enqueue
chore(db): add index on (project_id, started_at)

Types: feat, fix, chore, refactor, docs, test, ci, perf. Scope is usually the package/app (core, api, web, reporter, …). This pairs with changesets for automated versioning of published packages.

Pull request rules

Every change lands through a PR that:

• Links its issue (Closes #NN).
• Is squash-merged (clean, linear history — one commit per PR on main).
• Has a green CI (lint, typecheck, test, build) — enforced once the M0 CI workflow exists.
• Resolves all conversations before merge.
• Includes a changeset when it touches a published package (@flakemetry/*).
• Keeps stale approvals dismissed on new commits.

Enforced protection on main

Rule	State	Notes
Require a pull request	✅	no direct pushes to main
Required approvals	0	solo phase; raise to 1+ when contributors join
Dismiss stale reviews	✅	new commits invalidate prior approval
Required status checks	✅	ci (node 20) + ci (node 22) must pass; branch must be up to date (strict)
Linear history	✅	squash-only, no merge commits
Conversation resolution	✅	all threads resolved before merge
Force-push / deletion	🚫	blocked
Admin enforcement	off	owner may hotfix before CI exists; revisit at M6

Follow-ups as the project matures: require 1+ approvals, wire required CI check contexts, enable "require signed commits", and turn on admin enforcement. Tracked implicitly under the M0 CI issue and the M6 contributor-program issue.

Merge strategy (repo settings)

• Squash merge only — merge commits and rebase merges are disabled.
• Delete branch on merge — no stale branches.
• Auto-merge enabled — queue a PR to merge once checks pass.
• Squash commit title = PR title; body = PR body.

Release flow

1. PRs land on main with changesets.
2. A release workflow opens a Version PR bumping affected @flakemetry/* packages + changelogs.
3. Merging the Version PR publishes to npm (with provenance).

See Roadmap (M0 sets up changesets + CI) and Architecture (monorepo layout).