Catalog My learning Blog
Full-Stack Developer Course: React, .NET and SQL Server · Phase 15 · Lesson 146 · 7 min read

Git Workflow, Code Review and Technical Debt

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: Repository Rules, a Commit Convention, a PR Template and a Throughput Forecast
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Choose a Git workflow that supports continuous delivery, run code reviews that improve both code and people, manage technical debt deliberately, forecast delivery from data instead of guesses, and use branch protection and ownership rules as security controls.

Concept Explanation

Code that works is the start of engineering. How a team changes it together decides how fast and safely it can go on changing. The workflow question is how long branches live. Long-lived feature branches accumulate conflicts and hide integration problems until the end, while trunk-based development, where everyone merges small changes to the main branch at least daily, with feature flags hiding unfinished work, fits the continuous delivery and canary practices of Day 89. Release branches are still useful for maintaining shipped versions. Whatever the model, keep pull requests small, a few hundred lines at most, focused on one change, with a description that explains why. Small changes are reviewed faster and more carefully, and are easier to revert. Conventional commit messages, with a type such as feat or fix and a scope, make history readable and allow automated changelogs and version numbers.

Code review has several purposes: catch defects and security problems, spread knowledge, keep the codebase consistent, and mentor. Google's public engineering practices state a useful standard: approve a change once it definitely improves the overall health of the code, even if it is not exactly how you would have written it, because waiting for perfection stalls progress. Review for design, correctness, tests, security using the checklist of Day 137, readability, and consistency, and leave style to automated formatters and linters. Be specific and kind, distinguish required changes from suggestions, and respond quickly, since slow reviews are the largest source of delay in many teams. As an author, review your own diff first, keep the change small, and explain what to look at. Guard against two failure modes: rubber-stamp approvals to be nice, and gatekeeping by taste.

Technical debt is a metaphor for the extra future cost created by expedient choices, and it is useful only if handled with precision. Martin Fowler's quadrant distinguishes deliberate from inadvertent debt and prudent from reckless: shipping now with a plan to fix is a prudent, deliberate decision, while not knowing better practice creates inadvertent debt that you discover later. Record debt where it can be seen, with the cost it imposes, in the backlog or in a code comment linked to an issue, and prioritize it against features by asking what it slows down or endangers. Security debt, such as outdated dependencies, missing authorization tests, and an unmonitored service, deserves higher priority because its cost arrives suddenly. Practical habits include leaving code a little better than you found it, adding tests when you change untested code, and reserving regular capacity for maintenance instead of waiting for a cleanup quarter that never comes.

Estimation is hard because of the planning fallacy, and the cone of uncertainty shows that early estimates are wide. Better than a single number is a range and the reasoning behind it. Slice work into small, similar-sized items, and forecast from data: measure the team's throughput, the number of items finished per week, and run a Monte Carlo simulation over past weeks to produce a probability distribution of completion dates, which turns the conversation into we have an 85 percent chance to finish by this date. Distinguish a forecast from a commitment, communicate assumptions and risks, and revisit as facts change. The four DORA metrics from the Accelerate research, deployment frequency, lead time for changes, change failure rate, and time to restore service, measure the health of the delivery process itself, and they should be used to improve systems and never to rank individuals. Finally, protect the workflow with settings: require reviews and passing checks before merge, forbid force pushes to the main branch, require signed commits where you need to prove authorship, and use CODEOWNERS so that authentication, infrastructure, and pipeline changes always reach the people who understand them.

PracticeDoAvoid
BranchingShort-lived branches or trunk-based with flagsWeeks-long branches that merge at the end
Pull requestsSmall, one purpose, explain whyThousand-line changes nobody can review
ReviewImprove code health, respond fast, separate required from optionalRubber stamps and style wars
Technical debtRecord cost, prioritize by what it slows or endangersA vague list that never gets worked
EstimationSmall slices, throughput-based ranges, stated confidenceSingle-date promises from early guesses
Repository settingsRequired reviews, checks, CODEOWNERS, no force pushDirect pushes to main, unreviewed pipeline changes

Worked Example: Repository Rules, a Commit Convention, a PR Template and a Throughput Forecast

The settings protect main, the template shapes reviews, and the function forecasts from history.

Code
# Branch protection for main, expressed as code so it is reviewed and repeatable.
gh api -X PUT repos/acme/taskboard/branches/main/protection --input - <<'JSON'
{
  "required_status_checks": { "strict": true, "contexts": ["build", "test", "security / codeql"] },
  "enforce_admins": true,
  "required_pull_request_reviews": { "required_approving_review_count": 1, "require_code_owner_reviews": true, "dismiss_stale_reviews": true },
  "restrictions": null,
  "required_linear_history": true,
  "allow_force_pushes": false,
  "allow_deletions": false
}
JSON
Code
<!-- .github/pull_request_template.md -->
## What and why
<!-- The problem this solves, in two or three sentences. Link the issue. -->

## How to review
<!-- Where to start, what is risky, what you are unsure about. -->

## Checks
- [ ] Tests added or updated, including a negative case for anything security relevant
- [ ] No secrets, and no personal data in logs
- [ ] Database migration is backward compatible (expand, then contract)
- [ ] Feature flag in place if the change is user-visible and not complete
- [ ] Docs, runbook or ADR updated where behavior changed

Commit message format: type(scope): summary      e.g.  fix(tasks): reject cross-tenant project ids
Types: feat, fix, docs, refactor, test, chore, perf, security
Code
# CODEOWNERS
*                              @acme/taskboard-devs
/src/Api/Auth/                 @acme/security @acme/taskboard-leads
/infra/                        @acme/platform
/.github/workflows/            @acme/platform @acme/security
/docs/adr/                     @acme/taskboard-leads
Shell
// Monte Carlo forecast from throughput: "how many weeks until these N items are done?", as a distribution instead of a single guess.
export function forecastWeeks(weeklyThroughput: number[], itemsRemaining: number, runs = 10_000): { p50: number; p85: number; p95: number } {
  const results: number[] = [];
  for (let r = 0; r < runs; r++) {
    let done = 0, weeks = 0;
    while (done < itemsRemaining && weeks < 200) {
      done += weeklyThroughput[Math.floor(Math.random() * weeklyThroughput.length)];   // sample a past week at random
      weeks++;
    }
    results.push(weeks);
  }
  results.sort((a, b) => a - b);
  const at = (p: number) => results[Math.min(results.length - 1, Math.floor(p * results.length))];
  return { p50: at(0.5), p85: at(0.85), p95: at(0.95) };
}

// The last 12 weeks: items finished per week. 40 items remain.
const history = [4, 6, 3, 5, 7, 2, 5, 6, 4, 5, 3, 6];
console.log(forecastWeeks(history, 40));   // for example { p50: 8, p85: 10, p95: 11 }: an 85 percent chance to finish within 10 weeks

The forecast is only as good as the consistency of item sizes and the stability of the team, which is why slicing work into small, similar pieces improves every other practice in this lesson as well.

Short-lived branches and small pull requests keep integration cheap. Reviews aim to improve code health quickly and kindly. Technical debt is recorded with its cost, and delivery is forecast from measured throughput as ranges. Repository rules turn these habits into controls.
Short-lived branches and small pull requests keep integration cheap. Reviews aim to improve code health quickly and kindly. Technical debt is recorded with its cost, and delivery is forecast from measured throughput as ranges. Repository rules turn these habits into controls.

Real-World Examples

  • Google's public Engineering Practices documentation states that reviewers should favor approving a change once it improves the overall code health of the system, even if it is not perfect, and it discusses how to handle disagreements and how quickly to respond. The guidance is widely adopted because it balances quality with flow, and it explicitly warns against holding changes for personal preference.
  • The DORA research program, described in the 2018 book Accelerate by Nicole Forsgren, Jez Humble, and Gene Kim, found that teams with high deployment frequency, short lead times, low change failure rates, and fast recovery outperformed others on organizational goals, and that these went together instead of trading off. It changed the common belief that speed and stability are opposed.
Key TakeawaysKeep branches and pull requests small and merge them often behind feature flags, so changes stay easy to review and roll back. Review to improve code health quickly and kindly, and make technical debt visible with its cost, with security debt first. Forecast from throughput as ranges with stated confidence, use DORA metrics to improve the system, and protect the workflow with required reviews, checks, CODEOWNERS, and no force pushes.

Review Questions & Answers

They are reviewed sooner and more carefully because reviewers can understand them, they conflict less, and they are easy to revert if something goes wrong. Large changes tend to receive shallow reviews and delay merging.

The change should improve the overall health of the codebase and meet the team's requirements for correctness, tests, and security, even if the reviewer would have written it differently. Waiting for perfection blocks progress, while style is left to automated tools.

It uses the number of items the team actually finishes per period and simulates many possible futures from that history, producing a range with probabilities. It relies on measured performance instead of subjective size guesses.

Required reviews, status checks, CODEOWNERS, and a ban on force pushes ensure that changes to sensitive code and pipelines are seen by knowledgeable people and cannot bypass checks or rewrite history. They also give an audit trail of who approved what.