Forking Workflow

The Forking Workflow is the standard for open source contribution. Instead of pushing to a shared repository, each developer has their own fork, making contributions via pull requests.

How It Works

┌─────────────────────────────────────────────────────────┐
│                 UPSTREAM (Original Repo)                 │
│                 github.com/org/project                   │
│                                                          │
│              ←── Pull Request ←──                        │
│                                 ↑                        │
└─────────────────────────────────│────────────────────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    │                           │
┌───────────────────┴───────┐   ┌───────────────┴───────┐
│     YOUR FORK             │   │   THEIR FORK          │
│  github.com/you/project   │   │  github.com/them/...  │
│                           │   │                       │
│      ↑ push    ↓ clone    │   │                       │
└───────────────────────────┘   └───────────────────────┘
           │
┌──────────┴──────────────────────────────────────────────┐
│                    YOUR LOCAL MACHINE                    │
│                                                          │
│  origin → your fork                                      │
│  upstream → original repo                                │
└─────────────────────────────────────────────────────────┘

Step-by-Step Guide

Step 1: Fork the Repository

On GitHub:

1. Go to the original repository
2. Click "Fork" button
3. Choose your account

Now you have github.com/you/project.

Step 2: Clone Your Fork

git clone git@github.com:you/project.git
cd project

Step 3: Add Upstream Remote

git remote add upstream https://github.com/org/project.git

# Verify remotes
git remote -v
# origin    git@github.com:you/project.git (fetch)
# origin    git@github.com:you/project.git (push)
# upstream  https://github.com/org/project.git (fetch)
# upstream  https://github.com/org/project.git (push)

Step 4: Sync with Upstream

Before starting work:

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

Step 5: Create Feature Branch

git checkout -b fix-typo-in-readme

Step 6: Make Changes

# Edit files
git add README.md
git commit -m "Fix typo in installation section"

Step 7: Push to Your Fork

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

Step 8: Create Pull Request

On GitHub:

1. Go to the original repository
2. Click "New pull request"
3. Click "compare across forks"
4. Select your fork and branch
5. Create the PR

Keeping Your Fork Updated

Regular Sync

# Fetch upstream changes
git fetch upstream

# Merge into main
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

Sync Feature Branch

If your PR branch falls behind:

git checkout my-feature
git fetch upstream
git rebase upstream/main
git push --force-with-lease origin my-feature

Contributing Guidelines

Most projects have a CONTRIBUTING.md file. Read it!

Common requirements:

• Sign a CLA (Contributor License Agreement)
• Follow code style
• Include tests
• Update documentation
• Sign commits

Writing Good Contributions

Before Starting

1. Check existing issues: Avoid duplicate work
2. Check existing PRs: Someone might be working on it
3. Open an issue: Discuss before coding (for large changes)
4. Read contributing guide: Follow project standards

The Contribution

1. One thing per PR: Focus on single issue
2. Small changes: Easier to review
3. Include tests: If the project has them
4. Update docs: If needed
5. Follow style: Match existing code

PR Description

## Summary
Brief description of changes.

## Related Issues
Fixes #123

## Changes
- Fixed typo in README
- Updated installation instructions

## Testing
- [ ] Ran existing tests
- [ ] Added new tests (if applicable)

## Checklist
- [ ] Read CONTRIBUTING.md
- [ ] Followed code style
- [ ] Tests pass
- [ ] Docs updated

Responding to Review

Maintainers may request changes:

# Make requested changes
git add .
git commit -m "Address review: improve error message"
git push

Be patient and professional. Maintainers are volunteers!

Common Scenarios

Your PR Has Conflicts

git fetch upstream
git checkout my-feature
git rebase upstream/main
# Resolve conflicts
git add .
git rebase --continue
git push --force-with-lease

Maintainer Requests Squash

git checkout my-feature
git rebase -i upstream/main
# Change 'pick' to 'squash' for commits to combine
# Save and edit combined message
git push --force-with-lease

You Need to Update Your Branch

git checkout my-feature
git fetch upstream
git rebase upstream/main
git push --force-with-lease

Fork Best Practices

Keep Main Clean

Don't commit to your fork's main:

• Use feature branches
• Main should mirror upstream
• Makes syncing easier

Delete Merged Branches

# Local
git branch -d my-merged-feature

# Remote
git push origin --delete my-merged-feature

Use Descriptive Branch Names

fix/issue-123-login-bug
feature/add-dark-mode
docs/update-api-reference

Multiple Forks

If you contribute to many projects:

# Clone each
git clone git@github.com:you/project-a.git
git clone git@github.com:you/project-b.git

# Each has its own upstream
cd project-a
git remote add upstream https://github.com/org/project-a.git

cd project-b
git remote add upstream https://github.com/other-org/project-b.git

Summary

• Fork creates your personal copy on GitHub
• Clone your fork, add upstream remote
• Sync with upstream before starting work
• Work in feature branches
• Push to your fork, PR to upstream
• Keep your fork's main in sync with upstream
• Follow project contributing guidelines
• Be patient and professional with maintainers

In the next module, we'll explore advanced Git techniques.