GitHub Contributing

Read a contributing guide, fork or branch correctly, keep a small diff, and respond to review without rewriting shared history.

The guide is Git; the path is GitHub

GitHub Collaboration gave issues and pull requests a repeatable shape. This lesson is the outsider path: read the project's contributing guide, then send a change the maintainers can review. GitHub Fork already named origin and upstream. GitHub Pull Requests already opened a same-repo pull request. Here you choose the correct path and keep the diff small.

# These are Git. None of them is a GitHub contribution.
git add README.md
git commit -m "Note"
git push origin main

Use a disposable GitHub repository you own for the files and the write-access walkthrough. Write the fork commands; do not fire them at a popular project's Issues tab as homework.

Read before you write

Before you touch files on a project you do not maintain, read what that project already published. GitHub shows a contributing banner when CONTRIBUTING.md or .github/CONTRIBUTING.md exists. That banner is GitHub. The file is Git.

# Contributing

This repository accepts small, issue-linked changes.

## Before you write code
1. Read this file and the issue / pull request templates.
2. Search existing issues. Open one if the problem is not listed.
3. Wait for a maintainer to confirm the work is wanted, unless the issue already invites a pull request.

## How to send a change
- If you have write access: branch from the default branch. Do not commit on `main`.
- If you do not: fork on GitHub, clone your fork, add `upstream`, fetch, then branch from `upstream/main`.
- Keep one concern per pull request. Do not mix docs, refactors, and features.
- Open a pull request against the original default branch. Fill the pull request template. Link `Closes #N`.
- After review: commit the fix on the same branch and `git push`. Do not force-push once review has started.

## What we will not merge
- Drive-by reformatting of files you did not otherwise change
- Secrets, tokens, or generated files
- Changes that skip the issue when this file asked for one

# From a clone of a GitHub repository YOU own
git switch main
git pull origin main
git switch -c feature/contrib-guide

# Write CONTRIBUTING.md at the repository root, then:
git add CONTRIBUTING.md
git diff --cached
git commit -m "Add a contributing guide for small issue-linked changes"
git push -u origin feature/contrib-guide

Search existing issues. Open a complete issue when the guide requires one. GitHub Issues already required problem, expected result, and reproduction. A surprise pull request that skips that contract is why maintainers close drive-by work.

Fork or write-access branch

The contributing guide, not habit, chooses the path. Git does not know whether you are a collaborator. GitHub permissions do.

# You already have write access. CONTRIBUTING.md said: branch, do not commit on main.
git switch main
git pull origin main
git switch -c feature/contrib-note

# Make ONE small change the issue asked for, then:
git add README.md
git diff --cached
git commit -m "Note how outsiders should read CONTRIBUTING.md"
git push -u origin feature/contrib-note
gh pr create --base main --title "Note the contributing guide in README" --body "$(cat <<'EOF'
## Summary
Points README at CONTRIBUTING.md so a stranger knows how to send a change.

## Linked issue
Closes #1

## How to verify
1. Open README.md on this branch.
2. Confirm it links CONTRIBUTING.md.
3. Confirm no other files changed.
EOF
)"

GitHub cannot fork a repository into the same account that already owns it. That is why this workshop does not pretend you forked your own practice repo. The fork commands below are the real outsider path; they use ORIGINAL/REPO and YOU as placeholders, the same way GitHub Fork did.

Keep a small diff

A contribution is one concern. Maintainers review the patch, not your formatter. Before you open the pull request, inspect the range the review will see.

Open the pull request against the original

Same-repo pull requests used gh pr create --base main in GitHub Pull Requests. A fork-based contribution must name the original repository, or GitHub will open the conversation on your fork—where the maintainers are not watching.

# You do NOT have write access. Fork first (GitHub), then clone YOUR copy.
# origin = your fork. upstream = ORIGINAL/REPO. See GitHub Fork.

git switch main
git fetch upstream
git merge upstream/main
git push origin main
git switch -c feature/contrib-note

# Small change, commit, then:
git push -u origin feature/contrib-note
gh pr create --repo ORIGINAL/REPO --base main --head YOU:feature/contrib-note --title "Note the contributing guide in README" --body "$(cat <<'EOF'
## Summary
Points README at CONTRIBUTING.md so a stranger knows how to send a change.

## Linked issue
Closes #1

## How to verify
1. Open README.md on this branch.
2. Confirm it links CONTRIBUTING.md.
3. Confirm no other files changed.
EOF
)"

--head YOU:feature/contrib-note is GitHub's name for “the branch on this user's fork.” Git still pushed that branch to origin. GitHub stores the comparison. After it merges, fetch and update your fork's default branch the way the Fork lesson taught—do not push the original main.

Respond without rewriting shared history

GitHub Code Review already required this habit. It is the same habit when you are the outsider: requested changes are answered on the same feature branch with an ordinary push.

# Stay on feature/contrib-note. Review already started.
# Edit the same files the review named, then:
git add README.md
git diff --cached
git commit -m "Use the path the review asked for"
git push

# These rewrite history reviewers already read. Do not run them on a shared pull request:
# git push --force
# git push --force-with-lease

What not to invent

Guided practice: guide, then one change

1. 01
   Pick a repository you own

   Confirm git remote -v is your GitHub URL. Update local main.

2. 02
   Add the guide

   On feature/contrib-guide, add CONTRIBUTING.md with the two paths (write access versus fork), a small-diff rule, and “no force-push after review.” Open a pull request and merge it.

3. 03
   Open one issue

   File a complete issue: problem, expected result, reproduction. The work is a one-line README pointer to CONTRIBUTING.md.

4. 04
   Send the write-access change

   git switch -c feature/contrib-note. Make that one README change. Push. Open a pull request with Closes #N.

5. 05
   Request a change, then answer it

   Leave a review that asks for a clearer sentence. Fix it on the same branch. git push without force. Then merge if you are done.

6. 06
   Write the fork path

   On paper or in the lab notes, record gh pr create --repo ORIGINAL/REPO with --head YOU:feature/contrib-note. Do not run it against a project you do not maintain.

Independent lab: contributing path

1. On a GitHub repository you own, add CONTRIBUTING.md that names both paths (write-access branch versus fork), requires a small issue-linked diff, and forbids force-push once review has started. Land it through a short-lived pull request.
2. Open one complete GitHub issue. On feature/contrib-note, make a single matching change. Open a pull request that fills the template and includes Closes #N.
3. Request one change on that pull request. Answer with a new commit and git push. Do not use git push --force.
4. Write the fork-based command you would run without write access, including gh pr create --repo ORIGINAL/REPO. Do not open that pull request on a popular public project.
5. Write six lines: repository URL, issue number, pull request number, whether this walkthrough used write access or a fork, one sentence that distinguishes CONTRIBUTING.md from a GitHub label, and one sentence that distinguishes git push after review from git push --force.

Common contributing mistakes

Lesson review

You can read a contributing guide, pick fork or write-access branch, keep the change small, open the pull request against the original repository, and answer review without rewriting shared history. The unit project that walks a full reviewed pull request is Git Project: Reviewed Pull Request. A check reviewers can trust is GitHub Actions.

• I know CONTRIBUTING.md is a Git file GitHub surfaces, not a git contribute command.
• I can choose fork (no write access) versus a feature branch on the original (write access).
• I can open gh pr create --repo ORIGINAL/REPO from a fork head, or a same-repo pull request when I already have write access.
• I answer requested changes with git push on the same branch, not with force-push or git push upstream main.