Project: Contributing to an Open-Source-Style Repository

Build the mental model

This project stitches together everything from earlier chapters into the exact workflow real open-source contributors use: fork, clone, branch, remote, commit, and pull request, chained into one continuous flow.

Forking creates your own copy of a repo you don't own
Two remotes: origin is your fork (push here), upstream is the original (fetch only)
A focused feature branch keeps one change reviewable on its own
CONTRIBUTING.md documents the project's expected code style and process
The pull request is how your branch reaches the maintainer for review

Your fork is a snapshot taken at the moment you forked it. The original project keeps moving without you, so contributors add a second remote, upstream, to fetch its latest history without needing push access.

Remote	Points to
origin	Your fork -- this is what you push to
upstream	The original repository -- fetch only, you rarely (if ever) have push access

Read CONTRIBUTING.md first

Most active projects document exactly how they want contributions made -- code style, test requirements, commit message format. Skipping it is the single fastest way to get a well-intentioned pull request rejected.

text

FORK, CLONE, BRANCH, PUSH, PULL REQUEST
---------------------------------------
   UPSTREAM (original project on GitHub)
        |
        | 1. Fork (click "Fork" on GitHub's website)
        v
   YOUR FORK (your copy on GitHub -- this is "origin")
        |
        | 2. git clone <your-fork-url>
        v
   YOUR LOCAL CLONE
     origin   -> your fork      (you can push here)
     upstream -> original repo  (fetch only, no push)
        |
        | 3. git checkout -b feature-branch
        | 4. edit files, git commit
        | 5. git push origin feature-branch
        v
   YOUR FORK  --- 6. Open Pull Request (GitHub website) ---> UPSTREAM

Connect it to a real scenario

Fork on GitHub

Open the original project's page and click Fork. GitHub creates a full copy under your account in seconds -- there's no terminal command for this, only GitHub's servers can create it.

Clone your fork

Clone your fork, not the original -- this is what makes your local origin remote point at a repo you actually control.

Add the upstream remote

git remote add upstream <original-repo-url> so you can fetch the original project's latest changes without needing write access.

Read CONTRIBUTING.md

Check for a contributing guide before writing any code, and follow its style and process expectations.

Create a focused feature branch

git checkout -b <branch-name>, named for exactly the one change you're making.

Make the change and commit

Edit only what that one change requires, then commit with a clear message explaining why it matters.

Push to your fork

git push -u origin <branch-name> -- push to origin, your fork, never directly to upstream.

Open a pull request

On GitHub, you'll see a prompt to open a pull request from your pushed branch into the original project's main branch. Describe the change, reference any related issue, and submit.

origin = your fork (push here), upstream = the original repo (fetch only)
fork -> clone -> branch -> commit -> push to origin -> open PR flow
Read CONTRIBUTING.md and keep pull requests small and focused

Try the working example

bash

export GIT_AUTHOR_NAME="Maintainer Mia"
export GIT_AUTHOR_EMAIL="mia@opensourceproject.example"
export GIT_COMMITTER_NAME="Maintainer Mia"
export GIT_COMMITTER_EMAIL="mia@opensourceproject.example"
export GIT_AUTHOR_DATE="2026-01-01T09:00:00"
export GIT_COMMITTER_DATE="2026-01-01T09:00:00"

# 1. The "original" open-source project (stands in for the real GitHub repo)
git init --bare /tmp/upstream.git
git clone /tmp/upstream.git /tmp/seed-workdir
cd /tmp/seed-workdir
cat > README.md <<'EOF'
# Awesome CLI Tool

A small command-line tool for formatting timestamps.

## Contributing
See CONTRIBUTING.md before opening a pull request.
EOF
cat > CONTRIBUTING.md <<'EOF'
# Contributing

- Keep pull requests focused on a single change.
- Match the existing code style.
- Write a clear commit message describing the "why".
EOF
git add README.md CONTRIBUTING.md
git commit -m "Initial commit: project scaffold and contributing guide"
git push origin main

# 2. "Fork" it: create your own copy on GitHub (simulated as another bare repo)
git clone --bare /tmp/upstream.git /tmp/your-fork.git

# 3. Clone YOUR fork to your machine -- this becomes 'origin'
git clone /tmp/your-fork.git /tmp/contributor-workdir
cd /tmp/contributor-workdir

# 4. Add the original project as a second remote, 'upstream'
git remote add upstream /tmp/upstream.git
git remote -v

# 5. Create a focused feature branch and make ONE change
export GIT_AUTHOR_NAME="Contributor Chen"
export GIT_AUTHOR_EMAIL="chen@example.com"
export GIT_COMMITTER_NAME="Contributor Chen"
export GIT_COMMITTER_EMAIL="chen@example.com"
export GIT_AUTHOR_DATE="2026-01-02T10:00:00"
export GIT_COMMITTER_DATE="2026-01-02T10:00:00"

git checkout -b add-iso-week-support
cat >> README.md <<'EOF'

## ISO week support
Added support for formatting dates with the ISO 8601 week number.
EOF
git add README.md
git commit -m "Add ISO week number support to README"

# 6. Push to YOUR FORK (origin), never directly to upstream
git push -u origin add-iso-week-support
git log --oneline

You should see

Running git remote -v shows exactly the two-remote pattern: origin points at your fork, upstream at the original:

origin  /tmp/your-fork.git (fetch)
origin  /tmp/your-fork.git (push)
upstream        /tmp/upstream.git (fetch)
upstream        /tmp/upstream.git (push)

git log --oneline shows both real, reproducible commits:

8da9811 Add ISO week number support to README
63b1005 Initial commit: project scaffold and contributing guide

Pushing the feature branch reports:

To /tmp/your-fork.git
 * [new branch]      add-iso-week-support -> add-iso-week-support
branch 'add-iso-week-support' set up to track 'origin/add-iso-week-support'.

On GitHub's actual website, opening your fork now shows a 'Compare & pull request' banner for the add-iso-week-support branch. Clicking it opens a pull request against the original repository's main branch -- this exact step has no terminal equivalent.

5-minute try-it

Add a second focused commit to your branch (for example, updating CONTRIBUTING.md's own example), push it, and run git log --oneline on both your local clone and git --git-dir=/tmp/your-fork.git log --oneline to confirm the fork's history matches your local branch. Then explain in one sentence why pushing that same commit directly to upstream would fail.

One important caution

Never adding the upstream remote (or never fetching it), so your feature branch is based on a stale copy of the project and picks up avoidable merge conflicts later.

Bundling multiple unrelated changes into one pull request instead of keeping it focused on the single change described in the issue or CONTRIBUTING.md guidelines.

GitHub Docs: Configuring a remote for a fork — Git & GitHub