From b897949f431065403bb7f9328334bbab74497b2f Mon Sep 17 00:00:00 2001 From: Chinar Amrutkar Date: Sun, 12 Apr 2026 18:53:13 +0000 Subject: [PATCH 1/4] Add Git Branching Workshop -- exercises to build branching mental model --- .../en/blocks/git-branching-workshop/index.md | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 common-content/en/blocks/git-branching-workshop/index.md diff --git a/common-content/en/blocks/git-branching-workshop/index.md b/common-content/en/blocks/git-branching-workshop/index.md new file mode 100644 index 000000000..47872d22f --- /dev/null +++ b/common-content/en/blocks/git-branching-workshop/index.md @@ -0,0 +1,153 @@ ++++ +title = 'Git Branching Workshop' +time = 60 +[tasks] + 1='Explain the difference between local branches and remote branches' + 2='Create a new branch for a new piece of coursework' + 3='Submit a PR that contains only the commits for that piece of work' + 4='Identify when a PR contains commits from the wrong branch' +[objectives] + 1='Create a branch from main and keep it separate from other work' + 2='Submit a clean PR with only the relevant commits' + 3='Diagnose a mixed-commit PR and fix it' +[build] + render = 'never' + list = 'local' + publishResources = false ++++ + +This workshop addresses a problem we see regularly: trainees submit PRs that contain commits from other pieces of coursework. This happens because of a misconception about how branches work. This workshop builds the right mental model. + +Before this workshop, make sure you have completed [Using GitHub](../using-github) and read the [Trainee PR Guide](../../guides/reviewing/trainee-pr-guide). + +## The Core Problem + +When you submit coursework, each piece should come from its own branch. If you make two pieces of coursework on the same branch, your PR for coursework B will also contain all the commits from coursework A. This makes it impossible to review and merge them separately. + +This workshop will show you: +1. Why this happens +2. How to prevent it +3. How to diagnose it if it goes wrong + +--- + +## Part 1: Understanding Branches Visually (15 minutes) + +### Exercise: Map the Branch Structure + +Look at this diagram of a repository: + +``` +main: A -- B -- C -- D -- F + \ +topic-1: E +``` + +And this PR that was submitted: + +``` +main: A -- B -- C -- D -- F + \ +topic-1: E -- G -- H + \ +topic-2: (topic-2 was never branched from main) + G -- H -- I -- J +``` + +**Task:** In your own words, answer these questions: + +1. Which commits belong to topic-1? +2. If topic-2 was supposed to be a separate piece of work, what went wrong? +3. If you submitted a PR for topic-2, what would it contain? +4. What should topic-2 have been branched from? + +Share your answers with your group. + +--- + +## Part 2: Create Two Branches Correctly (25 minutes) + +### Exercise: Two Coursework Pieces, Two Branches + +Your trainer will share a link to a practice repository. For this exercise, you will complete two separate pieces of coursework on two separate branches. + +**Important:** Each branch must be created from `main`, not from the other branch. + +**Step 1: Branch for Coursework 1** + +- Clone the repository +- Create a new branch from `main` called `cw1` +- Make a change (edit any file), commit it +- Push `cw1` to your fork + +**Step 2: Verify your branch is clean** + +Before you make any more commits, check what commits are on your branch: + +``` +git log main..HEAD +``` + +This shows commits on your branch that are not on main. If it shows more than the commits you just made, something is wrong. + +**Step 3: Create Branch for Coursework 2** + +Now create a second branch, also from `main`: + +``` +git checkout main +git pull origin main +git checkout -b cw2 +``` + +Make a different change, commit it, push `cw2`. + +**Step 4: Verify cw2 is separate** + +Check the log for cw2: + +``` +git log main..HEAD +``` + +How many commits does it show? They should only be the one you just made. + +**What went wrong in the bad example:** The trainee created `cw2` from `cw1` instead of from `main`. This means `cw2` contains all of `cw1`'s commits as well. + +--- + +## Part 3: Diagnosing a Mixed-Commit PR (20 minutes) + +### Exercise: Find the Problem + +Your trainer will share a link to a PR that has a problem. This PR contains commits that should not be there. + +Use the GitHub interface to answer these questions: + +1. How many commits does this PR contain? +2. Look at the commit list -- are there any commits that don't belong to this piece of work? +3. Can you identify which branch these extra commits came from? +4. How would you fix this? + +**Hints:** + +- Click on the commits tab to see the full list +- Click on individual commits to see what changed +- Look for commits with messages that don't match the coursework description + +### Discussion (5 minutes) + +As a group: +- What was the problem in this PR? +- How would you avoid making the same mistake? +- What command would you run locally to check your PR before submitting? + +--- + +## Key Takeaways + +- **Every piece of coursework = its own branch, branched from `main`** +- If you need to start new coursework while waiting for a review, always branch from `main`, not from your current work +- `git log main..HEAD` tells you exactly what commits are on your branch and not on `main` +- Before submitting a PR, check the commits tab -- does every commit belong to this piece of work? +- If your PR has extra commits, the fix is: create a new branch from `main`, cherry-pick only the right commits, submit a new PR From 0f1614ef1aa9ab1a30a30d6bec031cb4beef1234 Mon Sep 17 00:00:00 2001 From: Chinar Amrutkar Date: Thu, 16 Apr 2026 21:27:28 +0000 Subject: [PATCH 2/4] Fix code block formatting and ASCII diagram rendering --- .../en/blocks/git-branching-workshop/index.md | 55 ++++++++++--------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/common-content/en/blocks/git-branching-workshop/index.md b/common-content/en/blocks/git-branching-workshop/index.md index 47872d22f..2c0d3d470 100644 --- a/common-content/en/blocks/git-branching-workshop/index.md +++ b/common-content/en/blocks/git-branching-workshop/index.md @@ -35,30 +35,32 @@ This workshop will show you: ### Exercise: Map the Branch Structure -Look at this diagram of a repository: +Look at these two diagrams of a repository. + +**Diagram 1: Clean branch structure** ``` -main: A -- B -- C -- D -- F - \ -topic-1: E +main: A--B--C--D--F + \ +topic-1: E ``` -And this PR that was submitted: +**Diagram 2: Problem - topic-2 was branched from topic-1, not main** ``` -main: A -- B -- C -- D -- F - \ -topic-1: E -- G -- H - \ -topic-2: (topic-2 was never branched from main) - G -- H -- I -- J +main: A--B--C--D--F + \ +topic-1: E--G--H + \ +topic-2: (branched from topic-1, not main) + I--J ``` **Task:** In your own words, answer these questions: -1. Which commits belong to topic-1? -2. If topic-2 was supposed to be a separate piece of work, what went wrong? -3. If you submitted a PR for topic-2, what would it contain? +1. In Diagram 1, which commits belong to topic-1? +2. In Diagram 2, what went wrong with topic-2? +3. If you submitted a PR for topic-2 from Diagram 2, what would it contain? 4. What should topic-2 have been branched from? Share your answers with your group. @@ -82,9 +84,9 @@ Your trainer will share a link to a practice repository. For this exercise, you **Step 2: Verify your branch is clean** -Before you make any more commits, check what commits are on your branch: +Before you make any more commits, check what commits are on your branch. In your terminal, run: -``` +```bash git log main..HEAD ``` @@ -92,9 +94,9 @@ This shows commits on your branch that are not on main. If it shows more than th **Step 3: Create Branch for Coursework 2** -Now create a second branch, also from `main`: +Now create a second branch, also from `main`. In your terminal: -``` +```bash git checkout main git pull origin main git checkout -b cw2 @@ -104,9 +106,9 @@ Make a different change, commit it, push `cw2`. **Step 4: Verify cw2 is separate** -Check the log for cw2: +Check the log for cw2. In your terminal: -``` +```bash git log main..HEAD ``` @@ -125,7 +127,7 @@ Your trainer will share a link to a PR that has a problem. This PR contains comm Use the GitHub interface to answer these questions: 1. How many commits does this PR contain? -2. Look at the commit list -- are there any commits that don't belong to this piece of work? +2. Look at the commit list. Are there any commits that do not belong to this piece of work? 3. Can you identify which branch these extra commits came from? 4. How would you fix this? @@ -133,11 +135,12 @@ Use the GitHub interface to answer these questions: - Click on the commits tab to see the full list - Click on individual commits to see what changed -- Look for commits with messages that don't match the coursework description +- Look for commits with messages that do not match the coursework description ### Discussion (5 minutes) -As a group: +As a group, discuss: + - What was the problem in this PR? - How would you avoid making the same mistake? - What command would you run locally to check your PR before submitting? @@ -146,8 +149,8 @@ As a group: ## Key Takeaways -- **Every piece of coursework = its own branch, branched from `main`** +- **Every piece of coursework gets its own branch, branched from `main`** - If you need to start new coursework while waiting for a review, always branch from `main`, not from your current work - `git log main..HEAD` tells you exactly what commits are on your branch and not on `main` -- Before submitting a PR, check the commits tab -- does every commit belong to this piece of work? -- If your PR has extra commits, the fix is: create a new branch from `main`, cherry-pick only the right commits, submit a new PR +- Before submitting a PR, check the commits tab. Does every commit belong to this piece of work? +- If your PR has extra commits, the fix is: create a new branch from `main`, cherry-pick only the right commits, submit a new PR \ No newline at end of file From 816c41f51efc640a8079707ada81c74087dca084 Mon Sep 17 00:00:00 2001 From: Chinar Amrutkar Date: Thu, 16 Apr 2026 21:30:49 +0000 Subject: [PATCH 3/4] Replace ASCII diagrams with Mermaid gitGraph diagrams per reviewer feedback --- .../en/blocks/git-branching-workshop/index.md | 47 ++++++++++++------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/common-content/en/blocks/git-branching-workshop/index.md b/common-content/en/blocks/git-branching-workshop/index.md index 2c0d3d470..6887d39bd 100644 --- a/common-content/en/blocks/git-branching-workshop/index.md +++ b/common-content/en/blocks/git-branching-workshop/index.md @@ -35,25 +35,38 @@ This workshop will show you: ### Exercise: Map the Branch Structure -Look at these two diagrams of a repository. - -**Diagram 1: Clean branch structure** - -``` -main: A--B--C--D--F - \ -topic-1: E +Look at this diagram of a repository: + +```mermaid +gitGraph + commit id: "A" + commit id: "B" + commit id: "C" + commit id: "D" + commit id: "F" + branch topic-1 + checkout topic-1 + commit id: "E" ``` -**Diagram 2: Problem - topic-2 was branched from topic-1, not main** - -``` -main: A--B--C--D--F - \ -topic-1: E--G--H - \ -topic-2: (branched from topic-1, not main) - I--J +And this PR that was submitted: + +```mermaid +gitGraph + commit id: "A" + commit id: "B" + commit id: "C" + commit id: "D" + commit id: "F" + branch topic-1 + checkout topic-1 + commit id: "E" + commit id: "G" + commit id: "H" + branch topic-2 + checkout topic-2 + commit id: "I" + commit id: "J" ``` **Task:** In your own words, answer these questions: From 6e7ef9a09ab89782d328ce7d15539208f4aa80db Mon Sep 17 00:00:00 2001 From: Chinar Amrutkar Date: Thu, 16 Apr 2026 21:39:24 +0000 Subject: [PATCH 4/4] Add VSCode alternative note and link to existing branching notes --- .../en/blocks/git-branching-workshop/index.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/common-content/en/blocks/git-branching-workshop/index.md b/common-content/en/blocks/git-branching-workshop/index.md index 6887d39bd..44e351108 100644 --- a/common-content/en/blocks/git-branching-workshop/index.md +++ b/common-content/en/blocks/git-branching-workshop/index.md @@ -20,6 +20,8 @@ This workshop addresses a problem we see regularly: trainees submit PRs that con Before this workshop, make sure you have completed [Using GitHub](../using-github) and read the [Trainee PR Guide](../../guides/reviewing/trainee-pr-guide). +Also look at the [branching notes in the Onboarding module](https://curriculum.codeyourfuture.io/itp/onboarding/sprints/1/prep/#branching) for a visual guide to creating branches. + ## The Core Problem When you submit coursework, each piece should come from its own branch. If you make two pieces of coursework on the same branch, your PR for coursework B will also contain all the commits from coursework A. This makes it impossible to review and merge them separately. @@ -35,7 +37,9 @@ This workshop will show you: ### Exercise: Map the Branch Structure -Look at this diagram of a repository: +Look at these two diagrams of a repository. + +**Diagram 1: Clean branch structure** ```mermaid gitGraph @@ -49,7 +53,7 @@ gitGraph commit id: "E" ``` -And this PR that was submitted: +**Diagram 2: Problem - topic-2 was branched from topic-1, not main** ```mermaid gitGraph @@ -88,6 +92,8 @@ Your trainer will share a link to a practice repository. For this exercise, you **Important:** Each branch must be created from `main`, not from the other branch. +These steps use the terminal. If you prefer, you can do this in VSCode using the Source Control panel instead -- the concepts are the same, only the interface is different. + **Step 1: Branch for Coursework 1** - Clone the repository