Arc 2 Quest 10

The Guild Protocol

Pull Requests, code review and workflows

The Master Archivist leads you into the Great Council Hall. Around a round obsidian table, empty seats bear the crests of different guilds. At the center, an immense register is chained to the table - the Central Chronicle Register. No one can write in it directly.

"Archivist, you now master branches, merges, history rewriting and distant portals. But you still need to understand the Protocol - the sacred rules that allow guilds to work together without chaos. No Archivist writes directly in the Central Register. Each one proposes their modifications, and the Grand Council examines them before accepting. This is the foundation of all collaboration."

Why not write directly on main?

Imagine: ten Archivists simultaneously push their modifications to main. One breaks the code, another introduces a bug, a third overwrites the fourth's work.

It is chaos. And this is exactly what happens in real projects when everyone does git push directly to the main branch.

The risks of pushing directly to main:

  • Broken code: someone pushes untested code, everyone is blocked
  • Cascading conflicts: merges become a nightmare
  • No review: no one checks quality before integration
  • No traceability: impossible to know why a change was made
  • Difficult rollback: if the problem is detected late, reverting is painful

In the most disciplined guilds, the main branch is sacred. No one touches it directly. Everything goes through the Protocol.

The Feature Branch workflow

This is the most common workflow in the professional world. The principle is simple:

1 Create a branch git switch -c
➡
2 Work commits
➡
3 Push git push
➡
4 Pull Request platform
➡
5 Review + Merge git merge 
main:     A---B-----------F (merge)
               \         /
feature:        C---D---E

Each step matters. Let's look at them in detail.

What is a Pull Request?

A Pull Request (PR) - called Merge Request (MR) on GitLab and Forgejo - is a formal request to merge one branch into another.

It is the digital equivalent of a petition to the Grand Council: you present your modifications, explain why they are necessary, and the Council examines your work before approving it.

What a Pull Request contains

  • A title that is clear and descriptive
  • A description that explains the "why" and the "how"
  • The list of commits included
  • The diff - the line-by-line modifications
  • Comments and review discussions
  • A status: open, approved, merged, closed

Pull Requests are not part of Git. They are a feature added by platforms (GitHub, GitLab, Forgejo, Bitbucket). But the underlying workflow (branch + merge) is 100% Git.

Anatomy of a good Pull Request

The title

The title should be short, clear and descriptive. It should say what the PR does, not how.

Good examples

  • Add registration form validation
  • Fix startup crash on Windows
  • Update security dependencies

Bad examples

  • Changes - too vague
  • fix - says nothing
  • WIP John's branch - not a title

The description

The description is your chance to explain:

  • Why this change is necessary
  • What changed (summary of modifications)
  • How to test (steps to verify it works)
  • What is not included (if relevant)

The size

A good PR is small and focused. It does one single thing. Aim for 50 to 200 lines of diff - not 2000.

"A good scroll presents one clear idea. A petition that mixes ten different subjects always ends up at the bottom of a pile, ignored by the Council."

Code review

Code review is the moment when one or more colleagues examine your modifications before merging.

What to look for during a review?

  • Does the code work? - Correct logic, no obvious bugs
  • Is the code readable? - Clear names, understandable structure
  • Is the code tested? - Are there tests for new behaviors?
  • Does the code follow conventions? - Style, naming, project architecture
  • Is the code necessary? - No dead code, no unnecessary duplication

Giving good feedback

Constructive

  • "We could simplify this loop with a map()"
  • "Why this choice? I'm curious about the context"
  • nit: for cosmetic details
  • Suggest solutions, not just criticism

Destructive

  • "This is bad"
  • "This is wrong" (without explaining why)
  • Criticizing without suggesting alternatives
  • Mixing important issues with cosmetic ones

Receiving feedback

  • Don't take it personally - the review is about the code, not about you
  • Respond to comments - even if it's just to say "good idea, I'll fix it"
  • Learn from every review - it is one of the best ways to improve

"The Council does not judge the Archivist. It judges the scroll. A good Archivist welcomes criticism with gratitude - it makes their chronicles better."

The Fork workflow

When you want to contribute to a project that does not belong to you (an open source project, for example), you cannot create a branch directly on the original repo. You then use the fork workflow:

  1. Fork: you create a copy of the repo on your own account
  2. Clone: you clone your fork locally
  3. Branch: you create a working branch
  4. Commits: you make your modifications
  5. Push: you push to your fork
  6. Pull Request: you open a PR from your fork to the original repo
Original repo (upstream)     Your fork (origin)       Your PC (local)
         |                        |                       |
         |    fork                |                       |
         |----------------------->|                       |
         |                        |    clone              |
         |                        |---------------------->|
         |                        |                       | branch + commits
         |                        |    push               |
         |                        |<----------------------|
         |    Pull Request        |                       |
         |<-----------------------|                       |

This is the standard workflow for contributing to open source projects on GitHub, GitLab or Forgejo. The owner of the original repo receives your PR and decides whether to accept it.

Branching strategies

How do you organize branches in a project? Several strategies exist. Here are the three main ones.

GitHub Flow Recommended

The simplest and most common strategy:

  • main is always deployable
  • For each task, you create a branch from main
  • You open a Pull Request
  • After review and approval, you merge into main
main:     A---B-------E---F-------I
               \     /     \     /
feature-1:      C---D       G---H

Ideal for: most projects, continuous deployment.

Git Flow

A more structured strategy with several permanent branches:

  • main: production code
  • develop: the integration branch
  • feature/*: feature branches (from develop)
  • release/*: release preparation (from develop)
  • hotfix/*: urgent fixes (from main)

Ideal for: projects with numbered versions (v1.0, v2.0...).

Caution: complex, many branches to manage. Don't use it without good reason.

Trunk-Based Development

Developers work directly on main (the "trunk") with very short-lived branches (a few hours max). Unfinished features are hidden behind feature flags.

Ideal for: large teams with a very solid testing infrastructure (Google, Facebook).

"GitHub Flow is the Protocol I recommend to young guilds. It is simple, effective, and sufficient for the vast majority of projects. You do not need the complexity of Git Flow before you have a good reason."

Protecting the main branch

On platforms (GitHub, GitLab, Forgejo), you can configure protection rules for the main branch:

  • Forbid direct push: everything must go through a Pull Request
  • Require a review: at least N people must approve
  • Require green tests: automated tests must pass
  • Forbid force push: prevent history rewriting
  • Require linear history: force rebase before merge

These rules are configured in the repo settings on the platform, not in Git itself. It is an extra layer of security on top of the Protocol.

Pull Request template

You can create a file .github/PULL_REQUEST_TEMPLATE.md (on GitHub/Forgejo) at the root of your project. When someone opens a Pull Request, this template pre-fills the description.

## Description
<!-- Describe what this PR does and why -->

## Type of change
- [ ] New feature
- [ ] Bug fix
- [ ] Refactoring
- [ ] Documentation

## How to test
<!-- Steps to verify it works -->

## Checklist
- [ ] Code compiles without errors
- [ ] Tests pass
- [ ] Documentation is up to date

It is an excellent way to standardize PR quality in a team. Everyone knows what to fill in, and reviews are more efficient.

Practical exercise - Simulating the Protocol

Simulate the full Pull Request workflow locally:

  1. Create a repo with a first commit on main
  2. Create a proposition/ameliorer-defenses branch
  3. Make 2 commits on that branch
  4. Examine the changes from main (simulate the review)
  5. Merge with --no-ff to create a merge commit
  6. Delete the merged branch
  7. Run the verification script

Step 1 - Create the repository and first commit

mkdir protocole-des-guildes
cd protocole-des-guildes
git init -b main
echo "# Defenses du Royaume" > defenses.txt
echo "" >> defenses.txt
echo "Les defenses actuelles protegent la cite." >> defenses.txt
git add defenses.txt
git commit -m "Creer le registre des defenses du royaume"

Step 2 - Create the proposal branch

git switch -c proposition/ameliorer-defenses

Step 3 - Make commits on the branch

First commit - add fortifications:

echo "" >> defenses.txt
echo "## Fortifications" >> defenses.txt
echo "- Reinforce northern walls with enchanted stone" >> defenses.txt
echo "- Add watchtowers at all four corners" >> defenses.txt
git add defenses.txt
git commit -m "Add fortification proposals"

Second commit - add training:

echo "" >> defenses.txt
echo "## Training" >> defenses.txt
echo "- Train guards in magical combat" >> defenses.txt
echo "- Establish doubled night patrols" >> defenses.txt
git add defenses.txt
git commit -m "Add training proposals"

Step 4 - Examine the modifications (simulate the review)

# Switch back to main
git switch main

# View the list of commits in the proposal
git log main..proposition/ameliorer-defenses --oneline

# View the detailed modifications
git diff main..proposition/ameliorer-defenses

This is exactly what a platform does when it displays the diff of a Pull Request. You are doing the same thing from the command line.

Step 5 - Merge with --no-ff

The --no-ff (no fast-forward) option forces the creation of a merge commit, even if a fast-forward would be possible. This is important because:

  • It creates a landmark in the history
  • You can clearly see where the branch was integrated
  • It matches what platforms do when they merge a PR
git merge --no-ff proposition/ameliorer-defenses -m "Merge the defense improvement proposal"

Step 6 - Delete the merged branch

git branch -d proposition/ameliorer-defenses

Step 7 - Check the history

git log --oneline --graph

You should see something like:

*   abc1234 Merge the defense improvement proposal
|\
| * def5678 Add training proposals
| * ghi9012 Add fortification proposals
|/
* jkl3456 Create the kingdom defense registry

Step 8 - Run the verification

bash verifier.sh
.\verifier.ps1

Command summary

Command Description
git switch -c branch Create a working branch
git log main..branch View commits on a branch
git diff main..branch View the diff of a branch
git merge --no-ff branch Merge with a merge commit
git branch -d branch Delete a merged branch

The Master Archivist rises and faces you. For the first time, he no longer looks at you as an apprentice.

"You have mastered the Guild Protocol. You know how to propose modifications, examine them, merge them cleanly. You understand why no one writes directly in the Central Register, and you know the strategies that allow guilds to collaborate at scale."

He places his hand on your shoulder.

"The Arc of the Branches of Destiny is complete. You are now a full-fledged Archivist - capable of working alone or in a team, managing branches and merges, contributing to any project. But your journey is only beginning."

He leads you toward a door you had never noticed. Behind it, a staircase descends into the depths of the Citadel.

"Beyond this door lie the Ancient Arts - the advanced techniques that only Masters use. There you will learn to set aside your work in progress, to pick a specific commit from another branch, to track down a bug in the history, and many other secrets. But that is for the next chapter of your story."