Fork & Contribute to Open Source

The Fork Workflow

When you want to contribute to a repository you don't own, you can't push directly — you don't have write access. The fork workflow solves this:

1. Fork — create your own copy of the repository under your GitHub account
2. Clone — download your fork locally
3. Branch — create a feature branch
4. Make changes — code, commit, push to your fork
5. Pull Request — open a PR from your fork to the original repo

Original Repo (upstream)          Your Fork (origin)
github.com/org/project     →     github.com/you/project
        ↑                               ↓
        └─── Pull Request ←────── Your changes

Step 1: Fork the Repository

1. Go to the repository on GitHub
2. Click the Fork button (top right)
3. Select your account as the destination

GitHub creates github.com/your-username/repo-name — an independent copy you fully control.

Step 2: Clone Your Fork

git clone git@github.com:your-username/repo-name.git
cd repo-name

Step 3: Add the Upstream Remote

Your fork is origin. Add the original repo as upstream so you can sync later:

git remote add upstream git@github.com:org/repo-name.git

# Verify
git remote -v
# origin    git@github.com:your-username/repo-name.git (fetch)
# origin    git@github.com:your-username/repo-name.git (push)
# upstream  git@github.com:org/repo-name.git (fetch)
# upstream  git@github.com:org/repo-name.git (push)

Step 4: Create a Feature Branch

Never work directly on main — always branch:

git checkout -b fix/typo-in-readme
# or
git checkout -b feature/add-dark-mode

Use descriptive branch names. Many open source projects have conventions — check the contributing guide (CONTRIBUTING.md) if one exists.

Step 5: Make Changes and Push

# Make your changes
git add .
git commit -m "Fix typo in README installation section"

# Push to YOUR fork (origin), not upstream
git push origin fix/typo-in-readme

Step 6: Open a Pull Request

1. Go to the original repository on GitHub (not your fork)
2. GitHub shows a banner: "your-username:fix/typo-in-readme had recent pushes"
3. Click "Compare & pull request"
4. Make sure the base is the original repo's main, not your fork's
5. Write a clear title and description
6. Submit

The maintainers are notified. They'll review, leave comments, or merge.

Keeping Your Fork in Sync

The original repo moves forward while your fork stays at the old state. Sync regularly:

# Fetch latest from upstream
git fetch upstream

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

# Push the updated main to your fork
git push origin main

For feature branches in progress:

git checkout feature/my-feature
git rebase upstream/main  # replay your commits on top of latest upstream

Sync before every new branch

Before starting any new contribution, sync your fork's main with upstream. Starting from stale code means your PR will have merge conflicts.

Responding to Review Feedback

Maintainers often request changes. Update your branch and push — the PR updates automatically:

# Make requested changes
git add .
git commit -m "Address review: use const instead of let"
git push origin fix/typo-in-readme

The PR timeline shows all commits. Reply to each comment when addressed.

Reading CONTRIBUTING.md

Most serious open source projects have a CONTRIBUTING.md that explains:

• How to set up the development environment
• Branch naming conventions
• Commit message format
• How to run tests before submitting
• Code style requirements

Always read it before your first contribution. Submitting a PR that ignores these guidelines wastes both your time and the maintainer's.

Good First Contributions

Start small. Good entry points:

• Fix typos — documentation corrections are always welcome
• good first issue label — maintainers tag beginner-friendly issues
• Improve documentation — add examples, clarify confusing sections
• Add tests — projects rarely have enough test coverage
• Fix a bug you personally encountered — you already understand it

tip

Open an issue before writing code for any significant change. Describe what you want to do and why. Maintainers can tell you if the change fits the project's direction before you spend hours on it.

Common Mistakes to Avoid

Mistake	What to do instead
PR to wrong base branch	Check base is original/main, not fork/main
Giant first PR	Start with small, focused contributions
No tests for new code	Add tests — most projects require them
Committing debug logs	Review your diff before pushing
Not reading CONTRIBUTING.md	Read it before anything else
Working directly on main	Always use a feature branch

The Full Command Reference

# Fork setup (once per project)
git clone git@github.com:you/repo.git
git remote add upstream git@github.com:org/repo.git

# Sync fork with upstream (regularly)
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# New contribution
git checkout -b feature/my-change
# ... make changes ...
git add .
git commit -m "Descriptive message"
git push origin feature/my-change
# → open PR on GitHub

# After PR is merged, clean up
git checkout main
git merge upstream/main
git branch -d feature/my-change
git push origin --delete feature/my-change