Forking & Pull Requests

Quick Summary

Forking creates your personal copy of someone else's repository on GitHub. Pull requests (PRs) are how you propose changes from your fork (or branch) back to the original project. Together, they form the foundation of open-source collaboration and team code review.

---

The Fork & PR Workflow

sequenceDiagram
    participant UR as Upstream Repo<br/>(original/project)
    participant FR as Your Fork<br/>(donnyaw/project)
    participant L as Local Clone

    UR-->>FR: 1. Fork on GitHub
    FR-->>L:  2. git clone (your fork)
    L->>L:    3. git remote add upstream
    L->>L:    4. Create branch, make changes
    L->>FR:   5. git push to your fork
    FR->>UR:  6. Open Pull Request
    UR->>UR:  7. Review & Merge
    UR-->>L:  8. git fetch upstream (stay updated)

---

Step-by-Step: Contributing to a Project

1. Fork the Repository

On GitHub, click the Fork button on the repository page. This creates github.com/donnyaw/project.

2. Clone Your Fork

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

3. Add Upstream Remote

git remote add upstream git@github.com:original-author/project.git

# Verify remotes
git remote -v

origin    git@github.com:donnyaw/project.git (fetch)
origin    git@github.com:donnyaw/project.git (push)
upstream  git@github.com:original-author/project.git (fetch)
upstream  git@github.com:original-author/project.git (push)

4. Create a Feature Branch

# Always branch from latest upstream main
git fetch upstream
git checkout -b fix/typo-in-readme upstream/main

5. Make Changes and Commit

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

6. Push to Your Fork

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

7. Create a Pull Request

On GitHub, navigate to your fork. GitHub will show a banner: "fix/typo-in-readme had recent pushes — Compare & pull request". Click it.

---

Writing Effective Pull Requests

PR Title

feat: add dark mode support for dashboard
fix: resolve memory leak in WebSocket handler
docs: update API authentication guide

PR Description Template

## What

Brief description of what this PR does.

## Why

Context: why is this change needed? Link to issue if applicable.

Closes #42

## How

Technical details about the implementation approach.

## Testing

- [ ] Unit tests pass
- [ ] Manual testing performed
- [ ] No regressions

## Screenshots (if UI change)

Before | After
--- | ---
![before](url) | ![after](url)

---

Keeping Your Fork Updated

# Fetch upstream changes
git fetch upstream

# Update your main branch
git checkout main
git merge upstream/main
# or: git rebase upstream/main

# Push updated main to your fork
git push origin main

Updating a PR Branch

# If upstream/main has new commits since your PR
git checkout fix/typo-in-readme
git fetch upstream
git rebase upstream/main

# Force push (safe — it's your branch)
git push --force-with-lease

---

Code Review Process

As a Reviewer

Action	How
Comment on specific lines	Click the + icon next to a line in the diff
Suggest changes	Use the "suggestion" feature for inline code edits
Approve	Submit review with "Approve"
Request changes	Submit review with "Request changes"

As a PR Author

Feedback	Action
Reviewer approved	Merge the PR
Reviewer requested changes	Make fixes, push, mark conversations as resolved
Merge conflicts	Rebase onto latest main, resolve conflicts

---

PR Merge Options on GitHub

Method	Result	Best For
Create a merge commit	Merge commit with all branch commits	Preserving full history
Squash and merge	Single commit on main	Cleaning up messy branch history
Rebase and merge	Individual commits replayed linearly	Linear history, clean commits

---

Troubleshooting

Problem	Cause	Fix
PR shows merge conflicts	main changed since your branch	Rebase: git fetch upstream && git rebase upstream/main
PR has too many unrelated commits	Branched from wrong point	Rebase onto upstream/main, squash irrelevant commits
Can't push to fork	SSH key issue or wrong remote	Verify git remote -v and SSH config
PR checks failing	CI/CD tests fail	Check the failure logs, fix, and push

---

Best Practices

• Always work on a branch — never commit directly to main in your fork
• Keep PRs small and focused — one PR = one logical change
• Write clear PR descriptions — reviewers shouldn't have to guess intent
• Respond to feedback promptly — keeps the review cycle moving
• Squash fixup commits before merging — "fix typo" commits don't belong in main history
• Link issues — use "Closes #42" to auto-close issues on merge

What's Next

1. Commits & Tags — Master commit anatomy and version tagging
2. GitHub Actions & CI/CD — Automate testing and deployment