Skip to content

Volume ITechnology

13.11.8 — Working on a Team: Pull Requests, Reviews and Branching Strategy ​

On your own, Git is a tool for saving and undoing. On a team of ten, it becomes the way you all avoid stepping on each other.

Ten people push to the same project every day. Someone has to decide what is allowed into the main line. Someone has to look at a change before it goes live. And when a bug appears at 3 am, someone has to be able to read the history and find out why a line exists.

This page shows how teams do it: the pull request, the review, the rules that protect main, how open-source contributors work without any access, and the habits that make a history readable.

1. What a pull request is ​

First, a fact that surprises people: a pull request is not a Git feature. Git itself has no such thing. It is a feature of hosting sites such as GitHub, GitLab and Bitbucket. (GitLab calls it a merge request, which is the same idea with a different name.)

A pull request (PR) is a web page that says: "I have work on branch feature/coupons. Please merge it into main." The page shows:

  • A title and description that explain the change.
  • The diff: every line that changed, file by file.
  • A conversation: comments on individual lines, and on the PR as a whole.
  • Checks: automatic jobs (build, lint, and so on) that run on your branch, each with a green tick or a red cross. Chapter 13.7 explains continuous integration.
  • Reviewers, and whether they have approved.
  • A merge button, which stays disabled until the rules are satisfied.

The purpose is a conversation before the change lands. It is a chance for a teammate to catch a bug, suggest a clearer name, or ask "why are we doing this?". It is also how knowledge spreads: reviewing is how people learn each other's code.

2. The everyday cycle (GitHub flow) ​

Most teams follow the same loop for every task. It is called GitHub flow.

①Branchgit switch -cfeature/coupons②Commitgit commitsmall, clear commits③Pushgit push -u originfeature/coupons④Open a pull requeston GitHub: "merge thisinto main?"⑤Review and checksteammates comment;automatic checks run⑥Merge, delete branchthen: git switch maingit pullrepeat for the next task
One cycle of team work. Every task gets its own short branch. Nothing reaches main without a pull request that others have looked at and the automatic checks have passed.

Here are the steps as commands. We build the coupon feature from Chapter 13.11.3.

Step 1: start from the latest main, and make a branch.

bash
git switch main
git pull
git switch -c feature/coupons

Never start from an old main. The pull makes sure your branch begins where the team is now, which means fewer conflicts later.

Step 2: work and commit. Small, clear commits (section 9 below).

bash
git add -p
git commit -m "Validate coupon codes"

Step 3: push the branch.

text
$ git push -u origin feature/coupons
To github.com:acme/shop.git
 * [new branch]      feature/coupons -> feature/coupons
remote: Create a pull request for 'feature/coupons' on GitHub by visiting:
remote:      https://github.com/acme/shop/pull/new/feature/coupons

GitHub prints a link to open the pull request. (If you use GitHub's command line tool, gh pr create does the same.)

Step 4: open the pull request. Write a title and a description (section 3).

Step 5: respond to review. Teammates comment. You fix things by making more commits on the same branch and pushing. The pull request updates itself, and the checks run again.

bash
git add -p
git commit -m "Reject expired coupons"
git push

Step 6: merge, then clean up. When the checks are green and a teammate approves, someone presses the merge button. Then update your laptop and delete the finished branch:

bash
git switch main
git pull
git branch -d feature/coupons

And you start again. A branch lives for one task, then it is gone.

Keeping your branch current ​

If main moves while you work, your pull request may start to conflict. Bring main in:

bash
git fetch origin
git rebase origin/main        # or: git merge origin/main
git push --force-with-lease   # only needed after a rebase

Chapter 13.11.6 explains the two choices. If others review your branch, merging main in is gentler, because it adds commits instead of rewriting them.

3. Writing a pull request that gets reviewed ​

A pull request is a message to a busy person. Make it easy to say yes.

Keep it small. A change of 100 lines gets read carefully. A change of 2,000 lines gets a quick "looks fine" and a hidden bug. If a task is big, split it into steps that each make sense on their own.

One purpose per pull request. Do not fix a bug, rename variables and upgrade a library in the same one. Each reason deserves its own review and its own revert.

Write a description that answers the reviewer's questions:

text
Title: Reject refunds outside the 30-day window

What
  The refund endpoint now checks the order date.

Why
  Support could refund year-old orders by pasting an old link (#482).

How I checked it
  Refunded a fresh order (works) and a 45-day-old order (rejected).

Notes for the reviewer
  The window is a constant in refund.ts. We may want it configurable later.

Four short headings: what, why, how you checked it, and anything to look at carefully. Add screenshots for visual changes. Teams save the structure in a file named .github/pull_request_template.md, and GitHub fills it into every new pull request.

Link the issue. Writing Fixes #482 in the description (or in a commit message) closes that issue automatically when the change is merged into the main branch.

Use a draft. If you want early feedback on unfinished work, open a draft pull request. It cannot be merged, and it tells reviewers "do not judge yet".

Read your own diff first. Before you ask anyone else, open the PR and read the changes yourself. You will find stray debug lines and forgotten files about half the time.

4. Reviewing someone else's pull request ​

Reviewing is a skill. A good review does not look for mistakes in the author. It looks for problems in the change.

What to look for, in rough order of importance:

  1. Does it do what the description says? Does it solve the real problem?
  2. Is it correct? Edge cases, error handling, what happens with empty or very large input.
  3. Is it safe? Secrets, permissions, user input going straight into a query (Chapter 8.5.1).
  4. Can you understand it? Names, structure, comments that explain why.
  5. Style and small things last, and ideally automated by a formatter so no human argues about them.

Three habits make reviews pleasant:

  • Ask questions instead of giving orders. "What happens if the coupon is empty?" teaches more than "Wrong."
  • Mark small remarks as optional. Many teams write nit: ("nitpick") before trivial suggestions, so the author knows they may ignore them.
  • Say what is good. One kind sentence costs nothing and changes the mood of the whole thread.

When you finish, you choose one of three: comment (just remarks), approve, or request changes (the author must respond before merging).

5. The three merge buttons ​

When a pull request is ready, GitHub offers three ways to merge it. They are exactly the options from Chapter 13.11.6:

ButtonWhat lands on mainPick it when
Create a merge commitAll the branch's commits, plus a merge commitYou want the full history and branch shape
Squash and mergeOne single commit with the whole changeBranches are short, one PR is one change
Rebase and mergeThe branch's commits, replayed in a straight lineYour commits are already clean and you want them kept

A team usually picks one and sets it as the only allowed option, so the history stays consistent. Squash and merge is the most common choice. After merging, tick Delete branch so stale branches do not pile up.

6. Protecting main ​

On a team, you do not want anyone, even a senior engineer in a hurry, to push straight to main. The hosting site lets you set branch protection rules, which Git itself cannot enforce:

  • Require a pull request before merging. Nobody pushes to main directly.
  • Require approvals (one or two reviewers).
  • Require status checks to pass, for example the build and the linter.
  • Require the branch to be up to date with main before merging.
  • Block force pushes and deletion of main. This protects the history from the dangerous commands in Chapter 13.11.4.

CODEOWNERS adds one more idea: some code needs a particular reviewer. A file named .github/CODEOWNERS maps paths to people or teams:

text
# Anyone touching payments code needs the payments team to approve
/src/payments/   @acme/payments-team
*.sql            @acme/database-team

GitHub then asks the right people automatically, and can refuse to merge until they approve.

You can also require signed commits. A signature (made with a GPG or SSH key) proves a commit really came from the person named in it, because the author name in Git is only text anyone can type. GitHub shows a "Verified" badge. Chapter 8.2 explains signatures.

These rules are the server-side enforcement from Chapter 13.11.5: a local hook is a suggestion, and a protected branch is a rule.

7. Contributing to a project you do not own: forks ​

You find a bug in an open-source library and want to fix it. You cannot push to their repository, because you are not a member. Instead you use a fork.

upstreamthe project's own repoyou cannot push hereorigin (your fork)your copy on GitHubyou can push hereyour laptopthe clone you editremotes: origin, upstreamforkclonepushpull request: "please take my change"git fetch upstream: stay up to date with the original
You usually cannot push to a project you do not own. So you copy it (a fork), work on your copy, and ask the owners to take your change with a pull request. You keep a second remote, upstream, to stay in step with the original.

A fork is your own copy of their repository, on GitHub. You push freely to it. Then you ask the owners to take your change with a pull request that goes from your fork to their repository.

bash
# 1. Click "Fork" on GitHub. Then clone YOUR fork:
git clone git@github.com:ana/their-library.git
cd their-library

# 2. Add the original as a second remote, called upstream:
git remote add upstream git@github.com:theirs/their-library.git
git remote -v
# origin    git@github.com:ana/their-library.git (fetch)   <- your fork
# upstream  git@github.com:theirs/their-library.git (fetch)  <- the original

# 3. Work on a branch, push it to YOUR fork, open a pull request on GitHub:
git switch -c fix/empty-input
git commit -am "Handle empty input"
git push -u origin fix/empty-input

Over time the original moves on. To stay in step, fetch from upstream:

bash
git fetch upstream
git switch main
git rebase upstream/main      # or merge
git push origin main          # update your fork's main

The names are conventions: origin is where you push, upstream is the project you follow. Inside a company, people usually skip forks and push branches straight to one shared repository. Forks matter for open source, where strangers cannot be given write access.

8. How teams organise their branches ​

Teams also need a rule for how branches are used. There are three common ones.

Trunk-based: one trunk, very short branchesmainshort branches, merged within a day or two, unfinished work hidden behind feature flagsGitFlow: several long-lived lines (plus short hotfix branches off main)mainreleasedevelopfeaturerelease branches get only bug fixes; finished releases are merged into main and back into develop
Left to right is time. Trunk-based has one long line and branches that live a day or two. GitFlow has several long-lived lines and many merges between them. The first suits software that ships continuously; the second suits versioned releases on a schedule.

Trunk-based development. There is one main line (the trunk). Everyone works on very short branches, a day or two at most, and merges back often. Unfinished work is hidden behind a feature flag: a setting that keeps new code switched off in production until it is ready, so unfinished code can still be merged safely. It is the best fit for software that is deployed continuously, and it is the default recommendation in Chapter 13.7.

GitHub flow is the loop from section 2: a short branch per task, a pull request, a merge. It is trunk-based development with a review step. It is what most teams actually run.

GitFlow uses several long-lived branches: develop for the next release, release/* for preparing one, hotfix/* for emergency fixes, and main for released code. It was designed for software with numbered versions and scheduled releases, such as a mobile app or a product installed by customers. For a website that deploys many times a day it is a poor fit, because long-lived branches mean big, risky merges.

How to choose? Ask: how often do we ship? Shipping daily points to trunk-based or GitHub flow. Shipping a numbered version every few months, and supporting old versions, points to GitFlow. When unsure, start simple.

9. Writing history that others can read ​

Every commit you make will be read by someone later: a teammate searching for why a line exists, or you, at 3 am, during an incident. git blame leads to a commit message. If it says "fix stuff", you hit a dead end. If it explains the situation, you have your answer.

Atomic commits. One logical change per commit. Not "morning's work", and never a commit that leaves the project unable to build. This is what makes review, revert and bisect all work (Chapter 13.11.7).

Messages that help. A short subject, a blank line, then the reason.

text
Reject refunds outside the 30-day window

The refund endpoint accepted any order id, so support could issue
refunds on year-old orders by pasting a stale link.

Fixes #482

The rules of thumb that most teams follow:

  • The subject is a command in the imperative: "Add", "Fix", "Reject", not "Added" or "Fixing". A good test: the subject should complete the sentence "If applied, this commit will…".
  • Keep the subject under about 50 characters, so it fits on one line in git log --oneline.
  • Leave one blank line, then explain why in lines of about 72 characters. The code already shows what. Only you can say why.
  • Mention an issue number to link the commit to the discussion.

Conventional commits is a convention that adds a machine-readable prefix: feat: for a new feature, fix: for a bug fix, docs:, refactor:, perf:, chore:. A ! after the type, or a BREAKING CHANGE: footer, marks a change that breaks existing users.

text
feat(cart): apply coupon codes
fix(refund): reject orders older than 30 days
feat(api)!: remove the v1 endpoints

Tools can then work out the next version number and write the changelog from the commit messages. Adopt it if you want that automation. If your team adopts the format without the tooling, you pay the cost of the typing and get none of the benefit.

Tidy before you share. Use git rebase -i and --autosquash on your own branch (Chapter 13.11.6) to fold "fix typo" commits away before reviewers see them. Once reviewers have started reading, add commits instead of rewriting, so they can see what changed since their last look. If the team squashes on merge, the final history will be tidy anyway.

10. Habits that keep a team happy ​

  • Pull before you start, and before you push. Most conflicts come from working on an old copy.
  • Never commit to main directly when it is protected. Even when it is not, do not.
  • Never force-push a shared branch. Your own branch, after a rebase, with --force-with-lease, is the one exception (Chapter 13.11.3).
  • Keep generated files, secrets and large binaries out. Use .gitignore (Chapter 13.11.1) and, for big files, Git LFS.
  • Do not leave branches rotting. Delete merged ones on the server and run git fetch --prune locally.
  • Share your hooks. Tools like Husky keep the pre-commit checks in the repository so everyone runs the same ones (Chapter 13.11.5).
  • Communicate about risky operations. If you must rewrite a shared branch, say so first, in the channel, not after.

What the interviewer will push on ​

These questions check whether you can work with other people through Git, which is most of the job.

"What is a pull request?" A request, on a hosting site, to merge one branch into another, with a diff, a discussion and automatic checks. The tell: saying it is not part of Git itself. A strong answer then says why teams use it: review before merging, and checks that must pass.

"Walk me through how you would contribute a feature on a team." The full loop: update main, create a branch, small commits, push, open a PR, respond to review with more commits, merge, delete the branch. Mentioning that the branch is short-lived and the PR is small shows you have done this for real.

"What is the difference between merge, squash and rebase when merging a PR?" Merge keeps every commit and adds a merge commit. Squash makes one commit. Rebase puts the commits in a line without a merge commit. Say which your team picks and why.

"How do you stop people pushing broken code to main?" Branch protection: require pull requests, approvals and passing checks, block force-push. Point out that a local hook can be bypassed, but server rules cannot.

"What is a fork, and how is it different from a branch?" A fork is a whole copy of a repository under your own account. A branch is a label inside one repository. You fork when you cannot push to the original.

"Trunk-based development or GitFlow?" Answer with a criterion, not a preference: how often do you ship? Continuous deployment favours short branches and feature flags. Versioned releases supported for months favour GitFlow. The wrong answer is the one that says either is "best".

"What makes a good commit message?" Imperative subject under about 50 characters, a blank line, a body that explains why, and an issue reference. Add that you write history for the person debugging at 3 am.

One thing to volunteer: say that you read your own diff before requesting review, and keep pull requests small. It signals that you respect reviewers' time, which is what senior engineers notice.

Recall

  • A pull request is a feature of the hosting site, not of Git: a page with a diff, discussion, automatic checks and a merge button. Its value is review before the change lands.
  • GitHub flow: switch main, pull, switch -c feature/x, small commits, push -u, open a PR, answer review with more commits on the same branch, merge, delete the branch.
  • A good PR is small and has one purpose, with a description covering what, why, how you checked, and where to look. Fixes #482 closes the issue on merge. Use draft PRs for early feedback, and read your own diff first.
  • Review the change, not the author: correctness and safety before style; ask questions; mark small remarks nit:.
  • Merge buttons: merge commit (full history), squash and merge (one commit), rebase and merge (straight line). Pick one for the whole team and delete the branch after.
  • Protect main: require PRs, approvals and passing checks; block force-push and deletion. CODEOWNERS routes reviews by path. Signed commits prove authorship. Server rules enforce; local hooks only suggest.
  • Forks: your own copy of someone else's repository. You push to origin (your fork), follow upstream (the original), and open a PR from fork to original.
  • Branching strategies: trunk-based (very short branches, feature flags, continuous deployment), GitHub flow (branch per task, PR), GitFlow (long-lived develop/release/hotfix, for versioned releases). Choose by how often you ship.
  • Commit hygiene: atomic commits; imperative subject under about 50 characters, blank line, then why; conventional commits only if you use the tooling; rewrite your own branch before review, add commits after.

Self-test: Why is a pull request not part of Git? · What goes in a good PR description? · What rules would you put on main, and why can a hook not replace them? · What is upstream, and when do you need it? · Trunk-based or GitFlow, and what decides it? · What are the parts of a good commit message?

Next: Chapter 15.2 widens the view from Git to the rest of the engineer's toolbox: how command-line tools work inside, diagrams as code, and the automation that removes the jobs nobody should do by hand.

Combine chapters into one PDF

Pick the chapters you want. They print in the order you pick them.

Volume I — Technology
Part 0 — Retention & Notation
Part 1 — Foundations of Computation
Part 2 — Operating Systems
2.1 The Kernel
2.2 Processes
2.3 Threads & Scheduling
2.4 Concurrency Under the Hood
2.5 Memory Management
2.6 File Systems
2.7 Input/Output
2.8 Linux for Engineers
2.9 Windows & macOS in Practice
Part 3 — Languages, Compilers & Runtimes
3.6 JavaScript & V8
3.7 TypeScript
3.8 Node.js Internals
3.13 Python & CPython
3.14 FastAPI & Production Python
Part 4 — Data Structures & Algorithms
4.0 Classic Problems — Before NeetCode
4.4 Arrays & Hashing — Problems
4.5 Two Pointers
4.6 Sliding Window
4.8 Stack — Problems
4.9 Linked List — Problems
4.11 Binary Search — Problems
4.13 Trees
4.14 Tree — Problems
4.15 Trie — Problems
4.17 Heap — Problems
4.18 Backtracking — Problems
4.19 Graphs
4.20 Graph — Problems
4.21 Advanced Graph — Problems
4.23 1-D DP — Problems
4.24 2-D DP — Problems
4.26 Greedy — Problems
4.27 Interval — Problems
4.28 Math & Geometry — Problems
4.30 Bit Manipulation — Problems
Part 5 — Networking & the Web
5.3 IP
5.4 Transport
5.6 HTTP
Part 6 — Frontend Engineering
6.1 Browser Internals
6.2 HTML & CSS Mastery
6.3 JavaScript in the Browser
6.4 React, from First Component to Full Shop
6.5 Frameworks & Rendering
6.8 UI Engineering & Patterns
Part 7 — Databases & Storage
7.2 SQL Mastery
7.3 Storage Engine Internals
7.4 Transactions
7.5 NoSQL Taxonomy
7.8 Analytics & Big Data
Part 8 — Security, Identity & Cryptography
8.2 Cryptography
8.3 Protocols of Trust
8.4 Identity: AuthN & AuthZ
8.5 Application Security
8.6 Infrastructure Security
Part 9 — Software Design (LLD)
9.2 OOP Foundations
9.3 Design Principles
9.4 Design Patterns
9.5 Concurrency
9.6 API Design
9.7 LLD Interview Machines
9.9 Node/Express Production Playbook
Part 10 — Distributed Systems & HLD
10.7 Consistency & Consensus
10.8 Messaging & Microservices
10.14 Caching
Building blocks from the design seat
Part 11 — System Design Case Studies
Part 12 — AI & ML Engineering
12.1 What AI Engineering Is
12.2 The Math You Need
12.3 Classical Machine Learning
12.4 Data for ML
12.5 Deep Learning
12.6 Embeddings & Vector Search
12.7 Transformers & LLMs
12.8 Building with LLMs
12.9 Retrieval-Augmented Generation
12.10 Agents
12.11 Adapting Models
12.12 Production AI
12.13 Multimodal AI
12.14 AI Security & Governance
12.15 Case Studies & Capstone
Part 13 — Cloud, DevOps & Infrastructure
13.11 Git, from First Commit to Team Workflow
Part 14 — Containers: Docker & Kubernetes
14.1 Foundations
14.2 Docker
14.3 Kubernetes
14.4 Kubernetes on Azure
Part 15 — The Craft & Career
Nothing picked yet