Branching Model¶

This project uses trunk-based development as defined in RFC FLX-ENG-RFC-001.

Branch table¶

Branch	Purpose	Lifetime	Merges into
`main`	Single source of truth. Always releasable. Protected — no direct push.	Permanent	—
`feature/<id>-<slug>`	One unit of work, scoped to a task or user story.	Hours to a few days	`main` via PR + green CI
`release/<version>`	Stabilisation window for an upcoming UAT or production cut. Only fixes allowed.	Days to two weeks	`main` (and tag)
`hotfix/<id>`	Urgent production fix on the currently released tag.	Hours	`main` + release tag

Rules and exclusions¶

Direct push to main is blocked. Every change lands through a PR with green CI and at least one reviewer.
release/* and hotfix/* PRs require two reviewers.
Feature branches rebase on main daily and merge within five working days.
Tags follow semantic versioning, cut from a release/* branch.
We do not create customer/<name> branches, long-lived dev branches, or environment branches.

Never create these branch types

customer/meesho, customer/myntra — customer variation is tenancy, not lifecycle
dev or develop — main IS the development branch
staging, production — environments are pipeline targets, not branches

Daily developer sync¶

# Start work
git switch main && git pull --rebase
git switch -c feature/TASK-123-awb-routing-fix

# Work...

# Daily rebase (keep feature branch current)
git fetch origin && git rebase origin/main

# Open PR
git push origin feature/TASK-123-awb-routing-fix
# → GitHub: create PR → CI runs → reviewer approves → merge → delete branch

Sprint-aligned release train¶

Day	Event	Owner
1–8	Normal development. PRs merge to main. Each merge auto-deploys to dev → staging → Flexli pilot.	All engineers
9	Release cut: `git tag v1.2.0-rc1` from `main`. QA regression sweep on staging.	Release DRI
10	Soft freeze on rc tag. Only release-blocker fixes (cherry-picked to `release/1.2`). New work continues on `main`.	Release DRI + QA
11	Promote to first pilot client (5–10% canary). Watch per-tenant SLIs for 24 h.	Release DRI + SRE
12	If canary green: full rollout. Publish release notes + manifest diff per client.	Release DRI
13–14	Retrospective. DORA metrics review. Runbook gap fixes.	Release DRI + Eng Lead

Versioning rules (SemVer with intent)¶

Change type	Version bump	Example
Breaking change to tenant manifest schema or client-facing API	MAJOR	`v2.0.0`
Sprint release (new features, non-breaking)	MINOR	`v1.3.0`
Hotfix between sprints	PATCH	`v1.3.1`

Hotfix fast path¶

# Branch off the release tag (not main)
git switch -c hotfix/TASK-456 v1.3.0
# Fix...
git push origin hotfix/TASK-456
# → PR (2 reviewers required) → merge to main → re-sign artifact + manifest
# → same canary rings, expedited (hours not days)
# → merge forward to main same day

How commit history is the audit trail¶

Every commit on main triggers CI which:

Builds the binary
Tags the OCI image: ghcr.io/flexli/dms:<semver>-<git-sha>
Attaches a CycloneDX SBOM (SHA-bound to the image)
Cosign-signs the image

The SHA is the immutable link:

git log → CI run → OCI image digest → SBOM → Cosign signature → audit log

Rollback = docker pull ghcr.io/flexli/dms:<previous-tag> + swap the previous signed manifest.