feat(root03): author Git & Collaborative Development

Adds all 6 ROOT 03 modules (why version control exists, the Git mental model, everyday Git, branching & merging, remote repositories, engineering Git workflow) — 31 activities. Uses only real LOCAL Git repositories throughout — no Gitea account, no network access, and no RootNode-canonical-repo credential is ever needed or exposed in a student Lab (docs/ROOT_FOUNDATIONS_LAB_STRATEGY.md §4). Modules 1, 2, and 6 are conceptual bookends with no lab, matching the flexible readiness standard already used in ROOT 01/02. Adds 3 new hands-on Git scenarios plus 2 MCQs: git-everyday-basics (init/add/commit, validated by inspecting real `git log`/`git show` state, not just command output strings — Step 6's explicit requirement), git-branching-and-merge (a REAL merge conflict caused on purpose by two branches editing the same line, resolved by the student, validated by confirming the conflict markers are gone and a real two-parent merge commit exists), and git-remote-clone-push (a real local bare repository standing in for a remote — clone/commit/push validated by inspecting the REMOTE side directly, not just the student's own clone). All tested end-to-end via the real scenario-validation API, including negative tests. Wires rootnode-git-fundamentals-assessment (2 required + 3 random-draw scenarios) using the existing Phase 3B assessment engine. Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-08-26 17:08:00 -05:00
parent e007bcf000
commit e68b6f445a
33 changed files with 1393 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Remote Repositories
+
+## What a remote actually is
+
+Every repository you've worked with so far has been entirely LOCAL — on this one machine. A
+**remote** is a reference to another copy of the same repository, typically hosted somewhere
+else (a server, or in this Lab, a second local repository playing that role). Remotes are what
+make real collaboration possible: multiple people, multiple machines, all synchronizing through
+one shared history.
+
+## `origin`: a name, not a special concept
+
+By convention, the remote you cloned FROM is named `origin` — but this is just a label Git
+assigns automatically, not a technical requirement. You could name a remote anything; `origin`
+is simply the default everyone recognizes.
+
+## The four remote operations
+
+- **`git clone <url>`** — copy an ENTIRE remote repository (full history included) to a new
+  local directory, automatically configuring it as `origin`.
+- **`git fetch`** — download the remote's latest commits WITHOUT changing your own working
+  files or branches — a safe way to see what's new before deciding what to do about it.
+- **`git pull`** — fetch AND immediately merge the remote's changes into your current branch —
+  effectively `fetch` + `merge` in one step (which is exactly why a `pull` can produce a merge
+  conflict, the same as Module 4's local merges).
+- **`git push`** — upload your local commits to the remote, making them visible to everyone else
+  using that remote.
+
+## Upstream: your branch's remote counterpart
+
+A local branch can be configured to TRACK a specific remote branch (its "upstream") — once set,
+plain `git pull`/`git push` (no extra arguments) know exactly which remote branch to sync
+against, rather than requiring you to specify it every time.
+
+## RootNode uses Gitea (this course does not)
+
+RootNode's own engineering team uses Gitea (a self-hosted Git service) for its real work — the
+CONCEPTS in this lesson (origin, clone, fetch, pull, push) are identical regardless of which
+service hosts a remote (Gitea, GitHub, GitLab, or a private server). This course teaches those
+concepts using a disposable LOCAL repository standing in for a remote — no account, no network
+access, and no RootNode credentials are ever needed or exposed in this Lab.
+
+## Instructor Notes
+
+**Lesson goal:** Teach remotes as a genuine, transferable concept — students should be able to
+work with ANY real Git hosting service afterward, not just this Lab's local simulation.
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Common misconception to watch for:** treating `git pull` as a "safe, no-side-effects" command
+— it's a merge, and merges can conflict, exactly like Module 4 taught.
+
+**Discussion question:** "Why might a team prefer `git fetch` followed by manually reviewing
+changes, over always running `git pull` directly?" (Answer: fetch lets you see what changed
+before it touches your own working files/branch — useful caution before merging in unfamiliar
+changes.)
@@ -0,0 +1,56 @@
+# Demonstration: A Complete Clone-to-Push Round Trip
+
+## OBSERVE
+
+A bare (remote-style) repository already exists, currently empty.
+
+```
+$ git clone /srv/demo-remote.git /srv/demo-clone
+warning: You appear to have cloned an empty repository.
+```
+
+Cloning an empty remote is completely normal — it just means no commits exist there yet.
+
+## HYPOTHESIS
+
+Predict what `git remote -v` will show inside the new clone.
+
+## INSPECT
+
+```
+$ cd /srv/demo-clone && git remote -v
+origin  /srv/demo-remote.git (fetch)
+origin  /srv/demo-remote.git (push)
+```
+
+Automatically configured as `origin` — exactly as the lesson described, with no extra setup.
+
+## CHANGE
+
+```
+$ echo "# Demo Project" > README.md
+$ git add README.md
+$ git commit -m "Add README"
+$ git push origin main
+```
+
+## VERIFY
+
+```
+$ git --git-dir=/srv/demo-remote.git log --oneline
+3f9a1c2 Add README
+```
+
+Checking the REMOTE directly (not the clone) proves the push actually reached it — the commit
+now exists in two places, in sync.
+
+## Instructor Notes
+
+**Demo goal:** Prove the push actually worked by inspecting the REMOTE side independently,
+not just trusting the clone's own `git log`.
+
+**Approximate timing:** 8 minutes live.
+
+**Common mistake to watch for:** assuming a successful `git push` with no error message means
+success without ever double-checking — worth reinforcing the "verify independently" habit from
+earlier ROOT_ modules.
@@ -0,0 +1,40 @@
+# Knowledge Check: Remote Repositories
+
+---
+
+**1. What's the difference between `git fetch` and `git pull`?**
+
+*Answer:* `git fetch` downloads the remote's new commits without touching your working files or
+branches. `git pull` does that AND immediately merges them into your current branch — it's
+fetch + merge combined.
+
+---
+
+**2. Why can `git pull` produce a merge conflict?**
+
+*Answer:* Because it performs a real merge under the hood — if your local branch and the
+remote's branch both changed the same lines differently, the same conflict situation from
+Module 4 can occur.
+
+---
+
+**3. Is `origin` a required, special name Git enforces?**
+
+*Answer:* No — it's just the conventional default name Git assigns to the remote you cloned
+from. You could name a remote something else; `origin` is a widely recognized convention, not a
+technical requirement.
+
+---
+
+**4. Does this course require a GitHub or Gitea account to learn remotes?**
+
+*Answer:* No — this course uses a disposable local bare repository to safely simulate a real
+remote, teaching the same concepts (clone/fetch/pull/push/origin) without any account or network
+access.
+
+## Instructor Notes
+
+**Facilitation:** Question 2 is worth emphasizing — many students assume `pull` is risk-free
+until they hit their first real pull-conflict.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,30 @@
+# Guided Exercise: Fetch First, Decide Second
+
+This is a paper exercise — commit to a plan before working in the Lab.
+
+## Your task
+
+You're about to sync with a shared remote that a teammate has been actively pushing to all day.
+You're not sure what they changed. Write out the SAFER sequence of commands (as opposed to
+running `git pull` immediately), and explain what each step lets you verify before your own
+working files are touched.
+
+## A worked shape to check yourself against
+
+```
+git fetch origin
+git log HEAD..origin/main --oneline
+```
+
+`git fetch` downloads the new commits without touching your branch. The `log` command then
+shows you exactly what commits exist on the remote that you don't have locally yet — letting you
+review WHAT changed before deciding to merge it in with a subsequent `git merge origin/main` (or
+`git pull`, now that you already know roughly what to expect).
+
+## Instructor Notes
+
+**Facilitation:** This exercise directly builds the "fetch first, review, then merge" habit
+real teams use on shared branches — worth connecting explicitly to why blind `git pull` on a
+busy shared branch is a common source of surprise conflicts.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced.
@@ -0,0 +1,24 @@
+# Reflection: You Just Practiced Real Collaboration, Safely
+
+## Reflection questions
+
+1. What would have felt different about this module's Lab if the remote were a real hosted
+   service (Gitea/GitHub) instead of a local simulation? What would have felt the same?
+2. Where do you expect `push` to matter most in real engineering work you'll do later?
+
+## Real Ops takeaway
+
+**Everything you just practiced — clone, commit, push, verified independently on the remote
+side — is the exact mechanism behind CI/CD and GitOps, which ROOT 11 covers later.** A CI
+pipeline triggers because someone pushed; a GitOps deployment happens because a change was
+pushed to a Git repository treated as the source of truth. You haven't just learned Git commands
+— you've practiced the literal trigger mechanism modern deployment automation is built around.
+
+This module is complete. Continue to the final module of this course.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 2 previews ROOT 11's GitOps content
+directly — worth naming that connection explicitly, even without teaching GitOps itself yet.
+
+**Approximate timing:** 5-8 minutes live discussion; 5 minutes self-paced writing.