GitHub Flow Collaboration: From Fork to Pull Request (PR)

Contributing code to open-source software, filing bug fixes, and collaborating within engineering teams on GitHub centers on the Pull Request (PR) model.

While developers may be accustomed to executing git push directly in single-developer workflows, collaborating on public repositories introduces essential concepts such as Forking, Upstream Remotes, and Branch Isolation.

This tutorial demonstrates the standard GitHub Flow to guide you through making clean, professional open-source contributions.

1. Overview of the GitHub Flow

A structured pull request lifecycle follows these six standard phases:

[Official Repository (Upstream)] 
       │ 1. Click Fork
       ▼
[Your Remote Fork (Origin)]
       │ 2. git clone
       ▼
[Local Development (Local)] ── 3. Create Feature Branch
       │                       4. Write Code & Commit
       ▼
[Push Branch to Origin] ── 5. Open Pull Request on GitHub
       │
       ▼
[Maintainer Review & CI] ── 6. Approved & Merged!

2. Step-by-Step Practical Walkthrough

Step 1: Fork the Upstream Repository

Open the project page you wish to contribute to (e.g. https://github.com/example/awesome-project).
Click the Fork button in the upper-right corner.
Select your personal account as the destination, keep branch copies as required, and click Create fork.
GitHub creates an independent copy under your namespace (https://github.com/your-username/awesome-project).

Step 2: Clone Locally & Configure the Upstream Remote

Clone your personal fork to your workstation:
```
git clone https://github.com/your-username/awesome-project.git
cd awesome-project
```
Speed Tip: For large repositories, accelerate the clone with GH-Proxy: git clone https://gh-proxy.org/https://github.com/your-username/awesome-project.git

Check configured remote tracking:

git remote -v

Initially, only origin pointing to your fork appears:

origin  https://github.com/your-username/awesome-project.git (fetch)
origin  https://github.com/your-username/awesome-project.git (push)

Crucial Step: Add the official repository as the upstream remote to sync future updates:
```
git remote add upstream https://github.com/example/awesome-project.git
```
Running git remote -v again will display both origin (your writable fork) and upstream (the official read-only base).

Step 3: Create an Isolated Feature Branch

Golden Rule: Never commit changes directly to the main or master branch of your fork! Keep your local main branch synchronized with upstream, and do all development work on dedicated feature branches.

# Ensure you are on the updated main branch
git checkout main

# Create and switch to a descriptive branch
git checkout -b fix/dark-mode-crash

Step 4: Write Code & Commit with Conventional Messages

Once you have written code and verified unit tests locally, stage and commit your changes:

# Check modified files
git status

# Stage changes
git add src/theme.js

# Commit with a clear Conventional Commit message
git commit -m "fix(theme): prevent null pointer exception on dark mode toggle"

Commit Prefix Conventions:

feat: Adds a new user-facing capability

fix: Resolves a bug or defect

docs: Documentation revisions only

style: Formatting changes without modifying logic

refactor: Structural reorganization without changing functionality

test: Adding or correcting test suites

Step 5: Push Feature Branch to Your Remote Fork

Push your feature branch to your GitHub repository (origin):

git push -u origin fix/dark-mode-crash

Step 6: Open the Pull Request on GitHub

Visit your repository page on GitHub.
A highlighted banner will appear: fix/dark-mode-crash had recent pushes. Click Compare & pull request.
Confirm branch direction:
- base repository: example/awesome-project (official repository) -> base: main
- head repository: your-username/awesome-project (your fork) -> compare: fix/dark-mode-crash
Provide a clear title and description:
- Detail the motivation and include relevant issue references (e.g. Fixes #123, which instructs GitHub to automatically close the issue upon merge);
- Complete any checkboxes defined in the repository PR template.
Click Create pull request.

Your pull request is now submitted to the project maintainers for automated CI testing and human code review.

3. Keeping Your Branch Synchronized with Upstream

While your PR is under review, maintainers may merge other commits into the official main branch. To eliminate merge conflicts, sync your branch regularly:

# 1. Switch to local main branch
git checkout main

# 2. Fetch the latest changes from official upstream
git fetch upstream

# 3. Merge upstream changes into your local main
git merge upstream/main

# 4. Push updated main to your personal GitHub fork
git push origin main

# 5. Switch back to your feature branch and rebase onto main
git checkout fix/dark-mode-crash
git rebase main

# 6. If conflicts arise, resolve them in your editor, then run:
# git add <resolved-file>
# git rebase --continue

# 7. Push rebased changes with lease protection:
git push origin fix/dark-mode-crash --force-with-lease

Safety Notice: Always prefer --force-with-lease over -f / --force. It verifies that no unexpected remote updates have occurred before overwriting history.

4. Addressing Code Review Feedback

If maintainers request alterations during review, do not close the PR to start over.

Simply continue making adjustments on your existing local feature branch:

# Edit code according to review feedback
git add .
git commit -m "refactor: apply reviewer suggestions"
git push origin fix/dark-mode-crash

GitHub automatically appends new commits to the open pull request, making your changes immediately visible to reviewers.