1. Fork the repo on GitHub. 2. Clone your fork: git clone . 3. Add upstream remote: git remote add upstream . 4. Create a branch: git switch -c feature. 5. Make changes and push. 6. Open a PR from your fork to the original repo.
✦ Definition~90s read
What is Forking and Contributing?
Forking creates a personal copy of someone else's repository on GitHub. You fork, clone your fork, make changes, and submit a Pull Request to the original repo. This is the standard open-source contribution model.
★
Imagine you want to suggest a change to a Wikipedia article.
Plain-English First
Imagine you want to suggest a change to a Wikipedia article. You can't edit it directly — you make a copy (fork), edit your copy, then submit a request to merge your changes back (Pull Request). The fork is your private sandbox where you can try anything without affecting the original. The maintainers review your changes and decide whether to accept them.
Forking is the foundation of open-source collaboration. You fork a repo, create changes in your personal copy, and submit a Pull Request. The maintainers review, discuss, and merge. The critical pattern that most beginners miss: keeping your fork in sync with the original (upstream) repository. A PR based on a stale fork will have merge conflicts that grow over time. This guide covers the full fork-and-PR workflow, the incident where a stale fork caused an 18-month-old PR, and how to keep your fork synchronized.
The Correct Fork and PR Workflow
Step 1: Fork the repository on GitHub (click 'Fork').
Step 2: Clone your fork locally: git clone git@github.com:yourusername/repo.git
Step 3: Add the original repo as 'upstream': git remote add upstream git@github.com:originalowner/repo.git
Step 4: Create a feature branch (NEVER work on main): git switch -c fix/typo-in-readme
Step 5: Make changes and commit.
Step 6: Push to your fork: git push -u origin fix/typo-in-readme
Step 7: Open a PR from your fork's branch to the original repo's main.
Step 8: Before creating your next PR, sync your fork: git switch main && git fetch upstream && git rebase upstream/main && git push
01_fork_workflow.shBASH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Clone your fork
gh repo clone yourusername/repo
cd repo
# Add upstream remote
git remote add upstream https://github.com/originalowner/repo.git
git remote -v
# Sync with upstream before starting work
git fetch upstream
git switch main
git rebase upstream/main
git push # update your fork's main
# Create a feature branch
git switch -c fix/readme-typo
echo 'Fixed typo' >> README.md
git add . && git commit -m 'docs: fix typo in README'
git push -u origin fix/readme-typo
# Open a PR
gh pr create --fill
# Later: sync for next contribution
git switch main
git fetch upstream
git rebase upstream/main
git push
Your fork's main branch should always mirror upstream/main exactly. If you commit to your fork's main, you can't cleanly sync with upstream. Always create a feature branch for each contribution. If you do commit to main accidentally: git reset --hard upstream/main to realign.
Production Insight
For teams contributing to open-source projects, maintain a local mirror script that syncs all active forks weekly. Use git fetch upstream && git rebase upstream/main && git push as a cron job. Add a contributing guide that includes the fork-and-sync workflow — it reduces stale PRs by 80%.
Key Takeaway
Fork = personal copy. Upstream = original repo. Never work on your fork's main branch. Keep main in sync with upstream. Create a feature branch for each contribution. Sync before every new PR to avoid merge conflicts.
● Production incidentPOST-MORTEMseverity: high
The 18-Month-Old PR That Could Never Be Merged
Symptom
A first-time contributor submitted a well-written PR fixing a documentation bug. They had forked the repo 18 months prior and never synced. The PR had 1,200 merge conflicts. Maintainers closed it as 'stale' after spending 2 hours trying to resolve conflicts.
Assumption
The contributor assumed forking was a one-time action. They didn't realize their fork would drift from the original repo over time, making their PR impossible to merge.
Root cause
1. Contributor forked the repo 18 months ago. 2. Made a small change on their fork's main branch. 3. Submitted a PR from fork/main to original/main. 4. Over 18 months, the original repo had 1,200+ commits. 5. The fork's main branch was 1,200 commits behind. 6. The diff between fork/main and original/main included thousands of unrelated changes. 7. Merge conflicts affected nearly every file. 8. Maintainers spent 2 hours manually resolving before giving up.
Fix
1. Closed the stale PR with a friendly message explaining why. 2. Contributor created a fresh fork and re-applied the change. 3. Submitted a new PR from a feature branch (not main) based on the latest upstream. 4. The new PR had zero merge conflicts and was merged within 24 hours. 5. Added a CONTRIBUTING.md guide explaining the fork-and-sync workflow.
Key lesson
Always keep your fork synchronized with upstream.
Never work on your fork's main branch.
Create a feature branch for each contribution.
Sync before creating a new PR: git fetch upstream && git rebase upstream/main.
Production debug guideUse this when production is on fire3 entries
Symptom · 01
I want to contribute to an open-source project
→
Fix
Fork the repo on GitHub, clone your fork, add upstream remote
Symptom · 02
My fork is behind upstream and I need to sync
→
Fix
Run git fetch upstream && git rebase upstream/main on your main branch
Symptom · 03
My PR has merge conflicts
→
Fix
Rebase your feature branch on the latest upstream: git rebase upstream/main
Key takeaways
1
Fork creates a personal copy
clone your fork locally
2
Add upstream remote pointing to the original repo
3
Never work on your fork's main branch
use feature branches
4
Sync with upstream before each contribution to avoid merge conflicts