Forking and Contributing — The PR That Was Open for 18 Months

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.

Why Fork? The Case for Controlled Collaboration

Forking a repository creates a personal copy under your GitHub account, giving you full control to experiment without affecting the original project. This is the foundation of the open source contribution model. Unlike direct branching on the upstream repo, forking decouples your work from the project's main development line. This is critical when you're not a core maintainer—you can't push branches to someone else's repo. Forking also protects the upstream from accidental force pushes or broken commits. In production, we've seen teams lose days of work because a contributor force-pushed to a shared branch. Forking eliminates that risk. Always fork before you start coding, even for small fixes. It's a habit that scales.

# Fork the repo on GitHub UI, then clone your fork
git clone https://github.com/YOUR_USERNAME/upstream-repo.git
cd upstream-repo

# Add upstream remote to sync with original
git remote add upstream https://github.com/ORIGINAL_OWNER/upstream-repo.git

# Verify remotes
git remote -v
# Output:
# origin    https://github.com/YOUR_USERNAME/upstream-repo.git (fetch)
# origin    https://github.com/YOUR_USERNAME/upstream-repo.git (push)
# upstream  https://github.com/ORIGINAL_OWNER/upstream-repo.git (fetch)
# upstream  https://github.com/ORIGINAL_OWNER/upstream-repo.git (push)

Syncing Your Fork: Stay Current or Get Left Behind

Your fork is a snapshot. While you work, the upstream repo evolves with new commits, bug fixes, and features. If you don't sync, your pull request will face merge conflicts or become outdated. The standard workflow is to fetch upstream changes and rebase your feature branch on top. Rebasing keeps a linear history, which maintainers prefer. Avoid merging upstream into your branch—it creates unnecessary merge commits. In production, we've seen PRs with 50+ merge commits that could have been a clean 3-commit series. Sync daily, or at least before you open a PR. Use git pull --rebase upstream main to keep your branch current.

# Ensure you're on your feature branch
git checkout my-feature

# Fetch upstream changes
git fetch upstream

# Rebase your feature branch onto upstream/main
git rebase upstream/main

# If conflicts occur, resolve them, then:
git add .
git rebase --continue

# Force push to your fork (since rebase rewrites history)
git push origin my-feature --force-with-lease

Branching Strategy: One Change, One Branch

Each contribution should live on its own branch. This keeps your work isolated and makes it easy to manage multiple PRs simultaneously. Name your branches descriptively: fix/login-error, feat/user-avatar, docs/api-guide. Avoid generic names like patch-1 or my-changes. In production, we enforce a branch naming convention: <type>/<short-description>. This helps CI scripts and maintainers quickly understand the purpose. Never commit directly to main on your fork—that branch should mirror upstream exactly. If you need to update your fork's main, sync it with upstream, don't push to it.

# Create a new branch from an up-to-date main
git checkout main
git pull upstream main
git push origin main  # sync your fork's main

# Create and switch to feature branch
git checkout -b fix/login-error

# Make changes, commit, and push
git add .
git commit -m "fix: handle empty email in login form"
git push origin fix/login-error

Commit Hygiene: Crafting a Clear History

Your commits tell a story. Each commit should be a self-contained, logical unit with a clear message. Follow the Conventional Commits specification: type(scope): description. For example, fix(auth): prevent null pointer on logout. Keep the subject line under 50 characters, and use the body to explain why, not what. Squash fixup commits before opening a PR. In production, we require all PRs to have a clean commit history—no 'WIP', 'fix typo', or 'oops' commits. Use git rebase -i to squash and reorder. This makes bisecting bugs trivial.

# Interactive rebase to squash last 3 commits
git rebase -i HEAD~3

# In the editor, change 'pick' to 'squash' for commits you want to combine
# Save and exit. Then write a new commit message.

# Force push the cleaned history
git push origin fix/login-error --force-with-lease

Opening a Pull Request: The Art of the First Impression

A good PR is more than code—it's communication. Write a descriptive title following the same convention as commits. In the description, explain what the change does, why it's needed, and how to test it. Reference related issues with Closes #123. Keep the scope narrow; a PR should do one thing. In production, we've rejected PRs that were too large to review effectively. Aim for under 400 lines changed. If your PR is larger, break it into smaller, dependent PRs. Use draft PRs for work in progress to signal that you're not ready for review.

## Description

Fixes the login error when email field is empty.

## Changes

- Added null check in `login.js`
- Updated error message to be user-friendly

## Testing

1. Go to /login
2. Leave email empty and click submit
3. See error message instead of crash

Closes #42

Code Review: Giving and Receiving Feedback

Code review is a conversation, not a gate. When reviewing, focus on correctness, maintainability, and adherence to project standards. Be specific: 'This function could throw if data is null' is better than 'This looks wrong'. When receiving feedback, don't take it personally. Address each comment, even if it's just to explain why you disagree. In production, we use a 'resolve conversation' button only after the issue is addressed. If a reviewer requests changes, make them and re-request review. Never dismiss reviews without discussion.

Reviewer: Could we add a null check here? If `user` is undefined, line 42 will crash.

Author: Good catch. Added a guard clause. Please re-review.

Reviewer: Looks good now. Approved.

Handling Merge Conflicts: The Inevitable Reality

Merge conflicts happen when two branches modify the same part of a file. The fix is to resolve them manually. Use git mergetool or an IDE. Understand both sides of the conflict—don't just keep your version. In production, we've seen conflicts that were resolved incorrectly, introducing bugs. After resolving, test the code. If you're unsure, ask the other author. To minimize conflicts, sync your branch frequently and communicate with other contributors about shared files.

# Rebase onto upstream/main to catch conflicts early
git fetch upstream
git rebase upstream/main

# Git will pause and mark conflicted files
# Edit the files to resolve conflicts (look for <<<<<<<, =======, >>>>>>>)

# After resolving:
git add .
git rebase --continue

# Force push
git push origin my-feature --force-with-lease

CI/CD and Testing: Let the Machines Check First

Before your PR is reviewed, automated checks should run: linting, unit tests, integration tests, and security scans. Most open source projects use GitHub Actions or similar. Run these tests locally before pushing to avoid wasting CI resources. In production, we've seen PRs that failed linting because the contributor didn't run npm run lint. Always run the project's test suite. If tests fail, fix them before requesting review. CI is your first line of defense—don't ignore it.

name: CI
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
      - run: npm test

After Merge: Clean Up and Celebrate

Once your PR is merged, delete your feature branch from your fork. This keeps your fork clean and prevents stale branches. Sync your fork's main branch with upstream. If your PR was part of a larger feature, update any related issues or documentation. In production, we automate branch deletion after merge using GitHub settings. Also, update your local repository: git checkout main && git pull upstream main && git push origin main. Then delete the local branch: git branch -d my-feature.

# Switch to main and sync
git checkout main
git pull upstream main
git push origin main

# Delete remote branch
git push origin --delete fix/login-error

# Delete local branch
git branch -d fix/login-error

Etiquette and Community: Beyond the Code

Open source is people. Be respectful in discussions, even when disagreeing. Read the project's contributing guidelines and code of conduct. If you're stuck, ask questions in the designated channels (issues, discussions, Slack). Don't demand features—propose solutions. In production, we've seen contributors get frustrated when their PR isn't reviewed immediately. Maintainers are often volunteers. Be patient and follow up politely after a reasonable time (e.g., one week). If your PR is stale, consider pinging with a friendly comment.

Hi maintainers, just checking in on this PR. I've addressed all the feedback. Let me know if there's anything else needed. Thanks!

Advanced: Managing Multiple Forks and Upstreams

Sometimes you need to contribute to multiple forks or track several upstreams. For example, you might fork a library, then fork another project that depends on it. Use multiple remotes to manage this. Name them descriptively: upstream-lib, upstream-app. You can also use git worktree to check out multiple branches simultaneously. In production, we use a script to automate syncing all forks. Be careful with force pushes when multiple remotes are involved—you might accidentally push to the wrong one.

# Add a second upstream
git remote add upstream-lib https://github.com/another-org/lib-repo.git

# Fetch from both
git fetch upstream
git fetch upstream-lib

# Create a branch tracking upstream-lib/main
git checkout -b lib-fix upstream-lib/main

# Make changes, then push to your fork
git push origin lib-fix

Common Pitfalls and How to Avoid Them

Even experienced contributors make mistakes. Common pitfalls include: forgetting to sync before creating a branch, committing directly to main, using git push --force instead of --force-with-lease, and not testing after resolving conflicts. Another is opening a PR from your fork's main branch—always use a feature branch. In production, we've seen all of these. The fix is discipline: follow the workflow every time, use scripts to automate repetitive steps, and double-check before pushing. If you mess up, don't panic—most mistakes are fixable with git reflog.

# If you accidentally reset or lost commits, use reflog
git reflog

# Find the commit hash you need, then reset to it
git reset --hard <commit-hash>

# Or create a new branch from that commit
git checkout -b recovery-branch <commit-hash>