Branching & Pull Requests

We use GitHub Flow, not GitFlow. Short-lived feature branches off main, one PR, squash-merge, delete. The one exception is a long-lived release branch when we still maintain an older version in a client’s production.

This page describes the intent. The rules are actually enforced by Azure DevOps branch policies — that’s the source of truth, this is the explanation.

Branch model

gitGraph
  commit id: "main"
  branch feature/12345-login
  checkout feature/12345-login
  commit id: "wip"
  commit id: "wip fix"
  checkout main
  commit id: "#12345" tag: "squashed"
  commit id: "..."
  branch release/1.x
  checkout release/1.x
  commit id: "hotfix"

The feature branch ends where it is — a squash-merge puts one new commit on main and deletes the branch. There is no merge commit.

• Branch names tie to the work item: feature/<id>-short-desc, bugfix/<id>-short-desc, hotfix/<id>-short-desc.
• main is always shippable. Nothing merges without a green build and a review.
• Squash-merge so main stays one clean commit per work item; delete the branch on merge.
• release/x.x exists only for a client version we still support — the documented escape hatch, not the default.

The code-review flow

sequenceDiagram
  actor Dev as Developer
  participant PR as Pull Request
  participant CI as Build Validation
  participant Rev as Reviewer
  Dev->>PR: Open PR (small, work item linked)
  PR->>CI: Trigger build + tests
  CI-->>PR: Must be green
  Dev->>Dev: Self-review the diff first
  Dev->>Rev: Request review
  Rev-->>Dev: Comments — "nit" vs "blocking"
  Dev->>PR: Resolve blocking comments
  Rev->>PR: Approve
  Dev->>PR: Squash-merge + delete branch

The policy (enforced, not optional)

Rule	Setting	Why
Small PRs	Target ≤ ~400 lines changed	Big PRs get rubber-stamped.
Minimum reviewers	1, self-approval off	Catch defects without blocking flow.
Required reviewers by path	Backend leads on backend/**, **/Migrations/**, devops/**	Enforceable as an Automatically included reviewers policy. Seniority-based rules are not — Azure DevOps cannot vary reviewer count by author.
Second reviewer	Convention, not policy: backend, security-touching, or a junior author	The tool can’t enforce it (see the row above), so the Team Lead does. Stated in The Daily Loop; expected of juniors.
Build validation	Required, must pass	Green means every blocking gate — see the gate list, including backend tests.
Reviewer SLA	Respond same working day	A stuck PR stalls the whole flow board.
Comment convention	Prefix nit: for non-blocking	Separates “must fix” from “nice to have”.

Note

Set these in Azure DevOps → Repos → Branches → main → Branch policies. If you change the policy, update this table in the same PR.

What a good PR description has

• What changed and why (link the work item).
• How it was tested (tests added, manual steps).
• Screenshots for any UI change (Angular / PrimeNG).