Branching, PRs & collaboration

1 · Branches — parallel work essential

Picture the day this goes wrong. You and a teammate both edit the same shared copy of the code at the same time. You're halfway through a risky change — a function that doesn't even compile yet — when your teammate pulls the code to ship an urgent fix. They get your broken, half-finished work, the build goes red, and now two people are blocked on a mess neither of them meant to create. This is the exact disaster branches exist to prevent, and it's why every professional team lives on them.

Here's the everyday analogy: a branch is like taking a photocopy of a shared document to scribble on. The original — main — stays clean on the shelf for everyone else. You scribble, cross things out, try three versions, make a total mess of your copy — and none of it touches the original until you walk over and say "okay, fold my changes in." The team never sees your rough drafts, only the finished edit.

Technically, a branch is astonishingly cheap: it's not a copy of your files at all, just a movable pointer to a commit (a single 40-character line in a hidden file). That's why branching in Git is instant and why the culture is "branch for everything, even a one-line fix" — you're not duplicating the project, you're just marking a new line of history. When you commit on a branch, the pointer slides forward to your new commit; main's pointer doesn't move. That separation is the whole game.

The mistake almost everyone makes early: committing straight to main "because it's just a small change." It feels faster, and it is — right up until that small change breaks the build for the whole team, or you need to ship something else urgently and now there's unfinished work sitting on the branch everyone deploys from. The discipline is simple: main is sacred and always shippable; your work-in-progress lives on a branch and merges back only when it's genuinely done. Learn it as a reflex now, on a solo repo, so it's automatic the day you're on a team of twenty.

A branch is an independent line of commits. Build each feature on its own branch so main stays stable and shippable; merge when ready.

branch.shgit switch -c feature/login       # create + switch
echo "def login(): ..." > auth.py
git add auth.py && git commit -m "feat: add login"
git switch main
git merge feature/login           # fast-forward or merge commit
git branch -d feature/login       # delete the merged branch

2 · Merge conflicts — routine, not scary essential

The first merge conflict you hit will make your stomach drop. You run git merge, expecting it to just work, and instead Git spits out CONFLICT and your file is suddenly full of angry arrows — <<<<<<<, =======, >>>>>>> — that look like the tool has corrupted your code. Almost every beginner's instinct at this moment is panic: "Did I break the repo? Did I lose my work?" You didn't. Nothing is lost, nothing is broken. This section exists to turn that stomach-drop into a shrug.

Here's the honest truth about what a conflict is: Git is a brilliant clerk but a terrible editor. When two branches change different parts of a file, Git happily stitches them together for you — that's a normal, silent merge, and it handles the overwhelming majority of cases. But when two branches change the very same lines, Git refuses to guess. It has no idea whether your teammate's version or yours is "correct," and it would rather stop and ask a human than silently pick wrong and ship a bug. A conflict isn't Git failing — it's Git being careful.

The analogy that makes it click: imagine you and a co-author both edit the same sentence in a shared essay. Your editor can't merge "The price is $10" and "The price is $12" into one true sentence — only a person who knows the actual price can. So it shows you both versions, side by side, wrapped in markers, and waits. That's exactly what those arrows are: <<<<<<< HEAD down to ======= is your side, and ======= down to >>>>>>> is the incoming side. Your job is to write the one correct sentence and delete all the scaffolding.

The classic mistake is leaving a marker behind — deleting the version you didn't want but forgetting to remove the ======= line, then committing. Now those seven equals-signs are sitting in your source code, and the file won't run. So the rule is: when you're done, the file must look like ordinary code with no arrows anywhere. And if you ever get lost mid-fix, git merge --abort rewinds everything to before the merge — a completely safe undo button. Knowing that escape hatch exists is what lets you approach conflicts calmly instead of fearfully.

When two branches change the same lines, Git can't auto-merge and marks a conflict. You just pick the correct final result.

conflict.shgit merge feature/pricing
# CONFLICT in config.py — Git inserts markers:
# <<<<<<< HEAD
# PRICE = 10          (main)
# =======
# PRICE = 12          (feature/pricing)
# >>>>>>> feature/pricing
# edit to the correct value, delete the markers, then:
git add config.py && git commit

3 · The pull-request workflow intermediate

Think about the last time someone pushed a change nobody looked at. Maybe it was you, at 6pm on a Friday: a "tiny, obviously-safe" tweak straight to main, no review, no second pair of eyes. Then it turned out the tweak wasn't obviously safe, and the whole team spent Monday morning untangling it. The pull request — the PR — is the ritual that makes "nobody looked at it" impossible. It's the single most important workflow in professional software, and it's the reason two engineers who've never spoken can safely ship into the same codebase.

So what is a pull request, really? The name confuses everyone at first — you're not pulling anything. A PR is a formal proposal: "I have some commits on my branch; I'm requesting that you review them and pull them into main." It's a doorway with a guard. Your branch sits outside main, visible to the whole team, and it can't get in until the checks pass and a human says yes. That's the entire idea — a review gate between your work and the shared code.

The analogy that lands: a PR is like submitting a pull request to merge into a shared essay, with track-changes on. Reviewers see exactly what lines you added and removed, they leave comments in the margin ("why 30 seconds and not 60?"), and you respond by pushing more commits — which don't open a new proposal, they update the same one in place. This is the detail beginners miss most often: a PR is a living conversation attached to a branch, not a one-shot snapshot. Push a fix, and the PR quietly updates; the reviewer just refreshes and sees your latest.

The common early mistake is treating the push and the PR as the same act — thinking git push "sends it for review." It doesn't. git push only uploads your branch to the shared server (origin); the PR is a separate step you open in the browser (or with gh pr create) that points at that pushed branch. Get that mental split right and the whole flow below reads cleanly: you push code to origin, then you open a request to merge it. Everything after — CI running tests, reviewers commenting, you addressing feedback — hangs off that one open request until it's approved and merged.

The professional PR flow

1. Branch off up-to-date main.
2. Commit; git push -u origin feature/x.
3. Open a PR; describe what changed and why.
4. CI runs tests+scans (TQ/CD); reviewers comment.
5. Address feedback, get approval, squash-merge, delete the branch.

pr.shgit switch main && git pull        # start from latest
git switch -c feature/search
# ...work, commit...
git push -u origin feature/search  # then open the PR on github.com
# after merge:
git switch main && git pull && git branch -d feature/search

4 · Advanced — code review that helps advanced

We've all received the review that helped nothing. Twenty comments, nineteen of them "add a space here," "move this brace," "you used single quotes" — and not one word about the off-by-one error that would've paged someone at 3am. Or the opposite: a two-second "LGTM 👍" on a 600-line change that nobody actually read. Both feel like review. Neither is. Learning the difference — and which side of it your own comments land on — is what turns you from a developer who gets reviewed into one whose reviews people are grateful for.

Here's the reframe that changes everything: a review is not a gate you defend, it's a gift you give. The goal isn't to catch the author being wrong or to prove you read carefully — it's to make the code better and the author smarter. That single shift in intent changes your tone, what you comment on, and what you let slide. You stop scoring points and start helping ship.

The analogy: think of the difference between an editor and a spell-checker. A spell-checker flags every typo and cares nothing for whether the argument holds together — that's the reviewer drowning a PR in formatting nits. An editor reads for meaning: does this actually work, is the tricky path handled, will the next person understand it in six months? You want to be the editor. The spell-checking? Hand it to a machine — a formatter and a linter in CI catch style automatically, so no human ever has to type "fix indentation" again. That frees your entire attention for the things only a human can judge: correctness, clarity, and risk.

The most common mistake in review is vagueness. "This is wrong" or "I don't like this" gives the author nothing to act on — it just starts an argument. Compare "this loop is O(n²) on the request path; a set lookup makes it O(n) — want me to sketch it?" That comment is specific (names the exact problem), constructive (offers a fix), and kind (it's about the code, not the coder). And be honest about severity: a genuine blocker and a passing "nit:" suggestion should never carry the same weight, or reviewers become the boy who cried wolf. The table below contrasts the weak reflexes with the strong habits — read each row as a small choice you make on every single PR.

5 · Advanced — automate PR quality advanced

Imagine being the person who has to say, on every single PR, "please rename your branch," "please write a real commit message," "this is too big to review — split it." You'd be exhausted, resented, and inconsistent — you'd enforce the rule when you had energy and wave it through when you didn't. Worse, the rules would live only in your head, so the day you're on holiday, standards quietly slip. Any policy that depends on a tired human remembering to check it is a policy that will be skipped. The fix is to hand the boring, mechanical checks to a machine.

The principle here is one of the most valuable in all of engineering: if a rule can be checked by a program, a human should never check it by hand. Machines don't get tired, don't play favourites, and apply the rule identically at 9am Monday and 6pm Friday. A person's judgment is precious and scarce — spend it on "is this design right?", not on "does this branch name match the pattern?" Automating the mechanical frees the human for the meaningful.

The analogy: think of the metal detector at an airport. No security officer frisks every passenger for keys and coins — the detector does the tedious, uniform screening so the humans can focus their attention on the genuinely suspicious. An automated PR check is that detector for your codebase: it runs on every pull request, flags the obvious violations (bad branch name, sloppy commit message, a diff so huge nobody can review it honestly), and lets your reviewers spend their energy on logic and risk. This is exactly the kind of job a CI — continuous integration — system runs automatically the moment a PR opens.

The trap to avoid is over-automating: don't try to make a script judge whether the code is good — it can't, and you'll just produce noisy false alarms that people learn to ignore. Automate only the objective, mechanical rules where "pass/fail" is unambiguous. The lab below is a tiny but real example: a pure-Python function that takes a PR's branch name, its commit messages, and its size, and returns a clean yes/no plus a list of exactly what's wrong. Read it as a template — this is precisely the shape of check a real CI job invokes on every PR, no human required.

pr_check.pyimport re
CONV = re.compile(r"^(feat|fix|docs|refactor|test|chore)(\(.+\))?: ")

def pr_mergeable(branch, commits, files_changed):
    problems = []
    if not re.match(r"^(feature|fix|chore)/[a-z0-9-]+$", branch):
        problems.append(f"bad branch name: {branch}")
    for c in commits:
        if not CONV.match(c): problems.append(f"non-conventional commit: {c!r}")
    if files_changed > 400:
        problems.append(f"PR too large ({files_changed} files) — split it")
    return (not problems), problems

ok, _ = pr_mergeable("feature/login", ["feat: add login", "test: cover login"], 12)
print("mergeable:", ok)
ok2, why = pr_mergeable("mystuff", ["did things"], 900)
print("mergeable:", ok2, "|", why)

mergeable: True
mergeable: False | ['bad branch name: mystuff', "non-conventional commit: 'did things'", 'PR too large (900 files) — split it']

6 · Professional — branching strategies professional

Here's a trap dressed up as best practice. A team reads a famous 2010 blog post about "Git Flow," sees the impressive diagram with develop, release, and hotfix branches all weaving together, and adopts the whole thing — because it looks professional and thorough. Six months later they're deploying continuously to a web app, drowning in ceremony, cherry-picking hotfixes across four branches, and wondering why shipping a one-line change takes two days. They cargo-culted a strategy built for a completely different problem. Choosing a branching model is a real engineering judgment, and getting it wrong quietly taxes every change you ever make.

A branching strategy is just the team's agreed answer to one question: "how does work travel from a developer's laptop into production?" There's no universally correct answer — the right one depends entirely on how often you ship. That's the insight that cuts through all the diagrams: match the model to your release cadence, and everything else follows.

The analogy: think of the difference between a food truck and a cruise-ship kitchen. The food truck (a web app deploying ten times a day) needs to serve fast, keep the line moving, and never let a big backlog build up — so it uses tiny, quick orders: short-lived branches, or even trunk-based development where changes land on main many times a day behind feature flags that hide unfinished work. The cruise-ship kitchen (versioned software shipped every few months — think installed desktop apps or firmware) plans elaborate multi-course meals well in advance, needs release and hotfix lanes to maintain old versions, and can absorb the ceremony because it ships rarely. Neither is "better" — they're solving different problems.

The mistake almost every team makes is the same one: long-lived branches. It feels safe to keep a big feature isolated on its own branch for three weeks — but merge pain grows with branch age. The longer your branch drifts from main, the more the world moves underneath it, and the more brutal the eventual conflict. That's why the modern default — GitHub Flow (branch off main, PR, CI, merge, done, all within a day or two) — beats heavier models for most teams: it keeps branches short and diffs small, so conflicts stay trivial. The table below lays out the three common strategies against exactly this axis — shape, and who each one is genuinely for.

7 · Tech-lead — protect main & own the flow tech-lead

You can write the best collaboration guidelines in the world, and someone will still push straight to main at midnight. Not out of malice — they were in a hurry, the guideline lived in a wiki nobody reads, and Git let them. Here's the hard-won lesson every tech lead learns: a rule that lives in a document is a suggestion; a rule enforced by the platform is a rule. If bypassing the process is even possible, then under deadline pressure it will happen — and the one time it happens is the time it breaks production.

So the tech lead's real job here isn't to write policy — it's to make the safe path the only path. This is what branch protection does: it's a set of switches on the platform (GitHub, GitLab, and the rest) that make it technically impossible to do the dangerous thing. No direct pushes to main. No merging without an approving review. No merging while CI is red. The rules stop being something people have to remember and become something the system simply won't let them violate.

The analogy: it's the difference between a "please don't enter" sign and a locked door. The sign depends on everyone reading it, agreeing with it, and choosing to obey it every single time — which they won't, forever. The locked door doesn't care about anyone's intentions or memory; it's just shut. Branch protection is the locked door. Note the subtlety that separates a good lead from a great one: strong policies enable enforce_admins, so the rules apply to the lead too. The protection you can personally bypass is a protection you'll eventually bypass "just this once" — and that's the crack the whole wall fails through.

The common mistake is treating protection as a one-time setup you flip on and forget. Settings drift: someone loosens a rule to unblock a release and never restores it, a new required check gets added but not enforced, an old one silently disappears. That's why the mature move is to treat the policy as data — a JSON config — and write a small check that audits it, so CI itself fails when protection weakens. The same config that sets the rules can drive the check that guards them. The labs below show both halves: a policy expressed as data, and a pure-Python audit that reports exactly which guardrails are missing.

protection.pydef protection_ok(rules):
    required = {"require_pr", "require_review", "require_ci_green", "no_direct_push"}
    missing = [r for r in required if not rules.get(r)]
    return (not missing), missing

strong = protection_ok({"require_pr":True,"require_review":True,"require_ci_green":True,"no_direct_push":True})
weak   = protection_ok({"require_pr":True,"require_review":False,"require_ci_green":False,"no_direct_push":False})
print("main protected:", strong)
print("weak config:", weak)

main protected: (True, [])
weak config: (False, ['require_review', 'require_ci_green', 'no_direct_push'])

git switch -c feature/greeting     # create + switch in one step
echo "hi there" > greet.txt
git add greet.txt
git commit -m "Add greeting file"
git switch main
git merge feature/greeting          # fast-forward if main did not move
git log --oneline --graph

git merge feature/rename
# Auto-merging app.py
# CONFLICT (content): Merge conflict in app.py

<<<<<<< HEAD
port = 8080          # your side (main)
=======
port = 9090          # incoming side (feature/rename)
>>>>>>> feature/rename

git add app.py
git commit            # completes the merge (default message is fine)

git switch -c fix/timeout
# ...make the fix...
git commit -am "Raise HTTP client timeout to 30s"
git push -u origin fix/timeout        # -u sets tracking so later `git push` suffices

gh pr create --fill                   # open PR from current branch (GitHub CLI)

# reviewer asks for a test -> add it, then:
git commit -am "Add test for timeout override"
git push                              # updates the same PR

git switch feature/api
git fetch origin
git rebase origin/main       # replays your commits on top of latest main
# resolve any conflicts, then:
git rebase --continue
git push --force-with-lease  # branch history rewritten; safe force

{
  "required_pull_request_reviews": {"required_approving_review_count": 1},
  "required_status_checks": {"strict": true, "contexts": ["ci/test"]},
  "enforce_admins": true,
  "allow_force_pushes": false,
  "required_linear_history": true
}

def audit(protection):
    problems = []
    pr = protection.get("required_pull_request_reviews", {})
    if pr.get("required_approving_review_count", 0) < 1:
        problems.append("main allows merging without approval")
    if not protection.get("required_status_checks", {}).get("contexts"):
        problems.append("main does not require green CI")
    if protection.get("allow_force_pushes"):
        problems.append("force pushes to main are allowed")
    return problems

cfg = {"required_pull_request_reviews": {"required_approving_review_count": 1},
       "required_status_checks": {"contexts": ["ci/test"]},
       "allow_force_pushes": False}
print(audit(cfg) or "policy OK")

Knowledge check check yourself