Hands-on lab — Day 33: Pull Requests and Code Review

#!/usr/bin/env bash
# Day 033 lab — completed reference implementation.
#
# Simulates the pull-request-and-review workflow entirely LOCALLY, with no
# GitHub account and no network. A pull request is just review and merge
# gates wrapped around Git branches and merges, so we can rehearse the whole
# logic with plain Git:
#
#   1. Create a throwaway repo with a LOCAL identity (never touches your global config).
#   2. Make a focused change on a `feature` branch and commit it.
#   3. Produce the "pull request": `git diff main..feature` and `git log main..feature`.
#   4. Simulate a round of review by adding an "addressed feedback" commit.
#   5. Merge with --no-ff to create a merge commit, like a PR merge, and show the graph.
#   6. Contrast a squash-merge on a second branch.
#
# Everything happens in a temporary directory that is removed on exit.
set -euo pipefail

# --- Set up an isolated throwaway repository ---------------------------------
# By default the throwaway repo is deleted on exit. The test harness sets
# PR_FLOW_KEEP=1 to inspect the final repo state; it then removes the dir itself.
work="$(mktemp -d "${TMPDIR:-/tmp}/pr-flow.XXXXXX")"
cleanup() { rm -rf "${work}"; }
if [ -z "${PR_FLOW_KEEP:-}" ]; then
  trap cleanup EXIT
fi

echo "Working in throwaway repo: ${work}"
git init -q -b main "${work}" 2>/dev/null || { git init -q "${work}"; git -C "${work}" symbolic-ref HEAD refs/heads/main; }
cd "${work}"

# A LOCAL identity, scoped to this repo only — your global Git config is untouched.
git config user.email "learner@example.com"
git config user.name "Course Learner"

# --- Seed main with an initial commit ----------------------------------------
cat > notes.md <<'EOF'
# Course Notes

## Day 33: Pull Requests
EOF
git add notes.md
git commit -q -m "Initial notes"
echo
echo "== main starts here =="
git log --oneline

# --- Step 1: branch off main, like starting a pull request -------------------
echo
echo "== Step 1: create a feature branch =="
git switch -c feature 2>/dev/null || git checkout -q -b feature

# --- Step 2: make ONE focused change and commit it ---------------------------
cat >> notes.md <<'EOF'

A pull request is a proposal to merge a branch, reviewed before it lands.
EOF
git add notes.md
git commit -q -m "Add greeting line to notes"
echo "Committed the focused change on 'feature'."

# --- Step 3: produce the "pull request" --------------------------------------
echo
echo "== Step 3: the PR — what you are proposing to merge into main =="
echo "--- git diff main..feature (the change) ---"
git --no-pager diff main..feature
echo
echo "--- git log main..feature (commits the PR would show) ---"
git --no-pager log main..feature --oneline

# --- Step 4: simulate review by addressing feedback --------------------------
echo
echo "== Step 4: reviewer asked to clarify wording — push a follow-up commit =="
# Reviewer comment: "spell out that review happens before the merge, plainly."
sed -i.bak 's/reviewed before it lands\./reviewed by teammates before it lands in main./' notes.md
rm -f notes.md.bak
git add notes.md
git commit -q -m "Address review: clarify wording"
echo "The PR now contains two commits (original + addressed feedback):"
git --no-pager log main..feature --oneline

# --- Step 5: merge with --no-ff, like a PR merge, and show the graph ---------
echo
echo "== Step 5: merge the PR with a merge commit (--no-ff) =="
git switch main 2>/dev/null || git checkout -q main
git merge --no-ff -q -m "Merge branch 'feature'" feature
echo "History after the merge (note the two-parent merge commit):"
git --no-pager log --graph --oneline

# --- Step 6: contrast a squash-merge on a second branch ----------------------
echo
echo "== Step 6: contrast the SQUASH strategy on a second branch =="
git switch -c feature2 2>/dev/null || git checkout -q -b feature2
cat >> notes.md <<'EOF'

Squash merge collapses a branch's commits into a single commit on main.
EOF
git add notes.md
git commit -q -m "wip: draft squash note"
# A messy second commit, the kind squash is meant to tidy away.
printf '\nStill drafting the squash example.\n' >> notes.md
git add notes.md
git commit -q -m "wip: fix typo"

git switch main 2>/dev/null || git checkout -q main
git merge --squash feature2
git commit -q -m "Add feature2 note (squashed)"
echo "feature2 had two 'wip' commits; squash landed them as ONE commit on main:"
git --no-pager log --graph --oneline

echo
echo "== Done. The merge commit and the squashed commit show the two strategies side by side. =="
if [ -n "${PR_FLOW_KEEP:-}" ]; then
  echo "PR_FLOW_REPO=${work}"
else
  echo "Throwaway repo ${work} will be removed on exit."
fi

lesson_id: D033
day: 33
kind: command-line-inspection
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-033-pull-requests-and-code-review
run_commands:
  - bash examples/pr_flow.sh
  - bash starter/pr_flow.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/pr_flow.sh  # optional: reset your edits (repos are temp dirs, auto-removed)'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (bash, system Git), bash tests/run_tests.sh → 11 checks, 0 failure(s).'

# Dependencies — Day 033 lab

**One dependency: Git.** This lab simulates the pull-request workflow with
local branches only, so it needs nothing beyond a shell and Git:

- `bash` ≥ 3.2 (preinstalled on macOS and every mainstream Linux distribution)
- `git` ≥ 2.0 (2.23 or newer preferred, so `git switch` is available; the
  scripts fall back to `git checkout` on older versions)
- Standard OS utilities: `mktemp`, `sed`, `printf` — all part of the base
  system on macOS and Linux.

There is no `requirements.txt`/`package.json` here; the scripts install
nothing.

## About a *real* pull request

A genuine pull request lives on a hosting platform (such as GitHub or GitLab)
and therefore needs, in real life:

- a free account on the platform, and
- network access to push a branch and open the request in the browser or with
  the platform's command-line tool.

This lab deliberately needs **neither**. Because a pull request is review and
merge gates wrapped around Git branches and merges, you can rehearse the entire
logic offline with the tools above. The lesson covers the account-and-network
side conceptually; you will open a real pull request in the Week 5 project.

#!/usr/bin/env bash
# Day 033 lab — YOUR working file: simulate a pull request locally.
#
# The scaffolding below creates a throwaway repo with a LOCAL identity and an
# initial commit on main. Your job is to complete the FIVE numbered exercises,
# each of which names the exact command to run. Replace every line that reads
#   : "FILL-IN ..."
# with the real command shown in the comment above it, then run:
#   bash starter/pr_flow.sh
#
# The completed reference is in examples/pr_flow.sh — try this yourself first.
set -euo pipefail

# --- Scaffolding (already done for you) --------------------------------------
work="$(mktemp -d "${TMPDIR:-/tmp}/pr-flow-starter.XXXXXX")"
trap 'rm -rf "${work}"' EXIT
echo "Working in throwaway repo: ${work}"
git init -q -b main "${work}" 2>/dev/null || { git init -q "${work}"; git -C "${work}" symbolic-ref HEAD refs/heads/main; }
cd "${work}"
git config user.email "learner@example.com"
git config user.name "Course Learner"
printf '# Course Notes\n\n## Day 33: Pull Requests\n' > notes.md
git add notes.md
git commit -q -m "Initial notes"
echo "main starts at:"; git --no-pager log --oneline

# --- Exercise 1: create a feature branch (like starting a pull request) -------
# Command:  git switch -c feature      (older Git:  git checkout -b feature)
: "FILL-IN exercise 1: replace this line with the branch-creating command"

# --- Make a focused change (already written for you) -------------------------
printf '\nA pull request is a proposal to merge a branch, reviewed before it lands.\n' >> notes.md

# --- Exercise 2: stage and commit the focused change -------------------------
# Commands:  git add notes.md   then   git commit -m "Add greeting line to notes"
: "FILL-IN exercise 2a: replace with 'git add notes.md'"
: "FILL-IN exercise 2b: replace with the commit command and message above"

# --- Exercise 3: produce the PR — the diff and the commit log ----------------
# Commands:  git --no-pager diff main..feature   then   git --no-pager log main..feature --oneline
echo; echo "== The pull request: what you propose to merge into main =="
: "FILL-IN exercise 3a: replace with the diff command above"
: "FILL-IN exercise 3b: replace with the log command above"

# --- Simulate review, then Exercise 4: commit the addressed feedback ---------
sed -i.bak 's/reviewed before it lands\./reviewed by teammates before it lands in main./' notes.md
rm -f notes.md.bak
# Commands:  git add notes.md   then   git commit -m "Address review: clarify wording"
: "FILL-IN exercise 4a: replace with 'git add notes.md'"
: "FILL-IN exercise 4b: replace with the commit command and message above"

# --- Exercise 5: merge the PR with a MERGE COMMIT (--no-ff) -------------------
# Commands:  git switch main    (older: git checkout main)
#            git merge --no-ff -m "Merge branch 'feature'" feature
#            git --no-pager log --graph --oneline
echo; echo "== Merge the pull request (merge-commit strategy) =="
: "FILL-IN exercise 5a: replace with the command to switch back to main"
: "FILL-IN exercise 5b: replace with the --no-ff merge command above"
: "FILL-IN exercise 5c: replace with the graph log command above"

echo; echo "== Done — you have simulated a pull request from branch to merge. =="

# Pull-request worksheet — Day 033

Fill this in for the change you made in the hands-on exercise. It is the same
thing you would type into the description box of a real pull request. Keep it
when you are done — a clear description you can point to is worth more than any
advice about writing one.

---

## 1. Pull-request description

Write it exactly as you would on a hosting platform.

**Title** (one line, imperative, under ~60 characters):

> _e.g. "Add greeting line to course notes"_

**Description** (what the change does and, crucially, *why*):

> _2–4 sentences. What did you change? Why was it needed? What problem does it
> solve or what does it add?_

**How I verified it** (tests, manual checks, the diff you read):

> _e.g. "Ran the script; git diff main..feature shows only the intended line;
> the merge produced a clean merge commit with no conflicts."_

---

## 2. What the diff shows

Paste the output of `git diff main..feature` (or list the files and the exact
lines it touched):

```text
_paste git diff main..feature here_
```

Files touched: _______________________________________________

Lines added / removed: ________________________________________

---

## 3. Merge strategy

Which strategy did you use to bring `feature` into `main`?

- [ ] Merge commit (`git merge --no-ff`)
- [ ] Squash and merge (`git merge --squash`)
- [ ] Rebase and merge

**Why this strategy fit this change** (2–3 sentences):

> _e.g. "I used a merge commit so the review-and-revise history — the original
> commit plus the 'addressed feedback' commit — stays visible in main." OR
> "I squashed because the two 'wip' commits were noise and I wanted one tidy,
> revertible commit on main."_

---

## 4. Reflection (optional but recommended)

In one or two sentences: what would a reviewer most likely comment on if this
were a real pull request, and how would you respond?

> _______________________________________________________________

#!/usr/bin/env bash
# Tests for the Day 033 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Runs the completed reference flow in an inspectable throwaway repo and
# verifies the real Git state a pull request produces:
#   - a `feature` branch exists with the focused change + an "addressed
#     feedback" follow-up commit (the diff/commits a PR would show),
#   - the merge-commit strategy (--no-ff) produced a two-parent merge commit,
#   - the squash strategy landed a second branch as a SINGLE commit on main
#     (its intermediate "wip" commits absent from main's history).
# No network is used. Exits 0 on success, non-zero on any failure.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# 1. The starter must be valid bash and still contain the five exercises.
echo "Checking starter/pr_flow.sh ..."
if bash -n "${lab_dir}/starter/pr_flow.sh" 2>/dev/null; then
  check "starter is syntactically valid bash" "yes"
else
  check "starter is syntactically valid bash" "no"
fi
exercise_count="$(grep -c 'FILL-IN exercise' "${lab_dir}/starter/pr_flow.sh")"
[ "${exercise_count}" -ge 5 ] && check "starter has at least 5 exercises" "yes" || check "starter has at least 5 exercises" "no"

# 2. Run the reference flow, keeping the repo so we can inspect the end state.
echo "Running examples/pr_flow.sh (kept for inspection) ..."
output=""
if output="$(PR_FLOW_KEEP=1 bash "${lab_dir}/examples/pr_flow.sh" 2>&1)"; then
  check "reference flow runs and exits 0" "yes"
else
  check "reference flow runs and exits 0" "no"
  echo "${output}" | sed 's/^/    /'
  echo; echo "${checks} checks, ${failures} failure(s)."
  exit 1
fi

repo="$(printf '%s\n' "${output}" | sed -n 's/^PR_FLOW_REPO=//p' | tail -n 1)"
if [ -n "${repo}" ] && [ -d "${repo}/.git" ]; then
  check "inspectable throwaway repo was created" "yes"
else
  check "inspectable throwaway repo was created" "no"
  echo; echo "${checks} checks, ${failures} failure(s)."
  exit 1
fi
# Always clean up the kept repo ourselves.
trap 'rm -rf "${repo}"' EXIT

g() { git -C "${repo}" "$@"; }

# 3. The feature branch exists (the PR's source branch).
g show-ref --verify --quiet refs/heads/feature && check "feature branch exists" "yes" || check "feature branch exists" "no"

# 4. The PR's commits are on feature: the focused change AND the review follow-up.
feat_log="$(g log feature --oneline 2>/dev/null)"
printf '%s\n' "${feat_log}" | grep -q "Add greeting line to notes" && check "feature has the focused change commit" "yes" || check "feature has the focused change commit" "no"
printf '%s\n' "${feat_log}" | grep -q "Address review" && check "feature has the addressed-feedback commit" "yes" || check "feature has the addressed-feedback commit" "no"

# 5. The diff a PR would show is non-empty between main's base and feature's tip
#    (feature's notes.md contains the proposed line).
g show "feature:notes.md" 2>/dev/null | grep -q "proposal to merge a branch" && check "git diff main..feature would show the proposed change" "yes" || check "git diff main..feature would show the proposed change" "no"

# 6. The no-ff merge produced a two-parent merge commit on main.
merge_count="$(g rev-list --merges --count main 2>/dev/null)"
[ "${merge_count:-0}" -ge 1 ] && check "merge-commit strategy created a merge commit (--no-ff)" "yes" || check "merge-commit strategy created a merge commit (--no-ff)" "no"

# 7. The squash strategy landed as a SINGLE commit on main; the wip commits are absent.
main_log="$(g log main --oneline 2>/dev/null)"
printf '%s\n' "${main_log}" | grep -q "squashed" && check "squash produced a single 'squashed' commit on main" "yes" || check "squash produced a single 'squashed' commit on main" "no"
wip_on_main="$(printf '%s\n' "${main_log}" | grep -c 'wip')"
[ "${wip_on_main}" -eq 0 ] && check "squash collapsed the branch (no wip commits on main)" "yes" || check "squash collapsed the branch (no wip commits on main)" "no"

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]