The Fork & Pull Request Model

The forking workflow is the standard collaboration model for open source projects. Instead of pushing directly to the original repository, you create your own copy (a fork), make changes there, and then propose those changes back via a pull request.

Why Fork?

In most open source projects, you don't have push access to the main repository. Forking solves this:

• You get your own copy of the repository that you fully control
• You can experiment freely without affecting the original project
• You propose changes through pull requests, which maintainers can review

The Forking Workflow

1. Fork          2. Clone           3. Branch
   (GitHub)         (your machine)     (your machine)

┌──────────┐    ┌──────────┐      ┌──────────┐
│ Original │    │ Your     │      │ feature  │
│ Repo     │──→ │ Fork     │──→   │ branch   │
│ (upstream)│    │ (origin) │      │          │
└──────────┘    └──────────┘      └──────────┘

4. Commit        5. Push            6. Pull Request
   (your machine)   (to your fork)     (GitHub)

┌──────────┐    ┌──────────┐      ┌──────────┐
│ Local    │    │ Your     │      │ Original │
│ Commits  │──→ │ Fork     │──→   │ Repo     │
│          │    │ (origin) │  PR  │ (upstream)│
└──────────┘    └──────────┘      └──────────┘

Step by Step

1. Fork the Repository

On GitHub (or GitLab, etc.), click the Fork button. This creates a copy of the repository under your account.

2. Clone Your Fork

git clone https://github.com/YOUR-USERNAME/project.git
cd project

This sets up origin pointing to your fork.

3. Add the Upstream Remote

Connect to the original repository so you can stay up to date:

git remote add upstream https://github.com/ORIGINAL-OWNER/project.git

Now you have two remotes:

git remote -v
origin    https://github.com/YOUR-USERNAME/project.git (fetch)
origin    https://github.com/YOUR-USERNAME/project.git (push)
upstream  https://github.com/ORIGINAL-OWNER/project.git (fetch)
upstream  https://github.com/ORIGINAL-OWNER/project.git (push)

4. Create a Feature Branch

Always work on a branch, never directly on main:

git checkout -b fix-typo-in-readme

5. Make Changes and Commit

# edit files...
git add .
git commit -m "Fix typo in README introduction"

6. Push to Your Fork

git push -u origin fix-typo-in-readme

7. Open a Pull Request

On GitHub, go to your fork and click "Compare & pull request". Write a clear description of your changes and submit.

Staying Up to Date

The original repository keeps getting new commits. To sync your fork:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

This pulls changes from the original repo into your local main, then pushes them to your fork.

Key Concepts

• origin — Your fork (you have push access)
• upstream — The original repository (you typically only fetch from here)
• Feature branches — Always branch off main for each change
• Pull requests — The mechanism to propose changes back to upstream
• Syncing — Regularly fetch from upstream to keep your fork current

When to Use the Forking Workflow

• Contributing to open source projects
• When you don't have write access to the original repository
• When strict code review is required before merging
• Large teams where direct push access should be limited