Intermediate Project: Contribute a Change to an Open Project
Fork, branch, commit, sync and tidy a contribution, audit it against written rules, and draft a clear pull request.
In this lesson you will
- Plan a contribution from fork to pull request
- Audit a contribution against written rules
- Fix findings with amend, rebase and push
- Draft an accurate pull request description
About 40 minutes
Your first contribution
This project puts the whole Intermediate level together. Asha wants to fix a problem in Dev’s project: issue 3 says Tuesday needs a backup volunteer. She will fork the project, branch from the latest main, make one small change, name the issue, tidy it, push it to her fork, and prepare a pull request. The work is real Git, and the website steps are described patterns.
The plan
- Fork the original project and clone your fork. Add the original as the
upstreamremote. - Create a branch whose name says what it is for, with the issue number in it.
- Make one small change and commit it.
- Fetch the original’s news, bring your branch up to date, and push the branch to your fork.
- Check the contribution against the project’s rules, then open the pull request.
Make the change
The session below starts with the original project, a fork and a clone, as in lesson 15. Asha creates the branch, changes the rota, and commits it. Her first commit message is lazy, because it is late and she is tired. Meanwhile, the maintainer adds a new commit to the original and pushes. Asha fetches and looks at the graph.
$ mkdir maintainer
$ cd maintainer
$ git init
Initialized empty Git repository in /home/nia/maintainer/.git/
$ printf "Beans: row 1\n" > plan.txt
$ printf "Mon: Nia\nTue: Dev\n" > rota.txt
$ printf "# Contributing\n\nPick an open issue, branch from main, and name the issue in your commit.\n" > CONTRIBUTING.md
$ git add .
$ git commit -m "Add plan, rota and contributing notes"
[main (root-commit) ff55e83] Add plan, rota and contributing notes
3 files changed, 6 insertions(+)
create mode 100644 CONTRIBUTING.md
create mode 100644 plan.txt
create mode 100644 rota.txt
$ cd ..
$ git init --bare upstream.git
Initialized empty Git repository in /home/nia/upstream.git/
$ cd maintainer
$ git remote add origin ../upstream.git
$ git push -u origin main
To ../upstream.git
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
$ cd ..
$ git clone --bare upstream.git fork.git
Cloning into bare repository 'fork.git'...
done.
$ git clone fork.git my-copy
Cloning into 'my-copy'...
done.
$ cd my-copy
$ git config user.name "Asha Rao"
$ git config user.email "asha@example.com"
$ git remote add upstream ../upstream.git
$ git switch -c fix-3-tuesday
Switched to a new branch 'fix-3-tuesday'
$ sed -i 's/Tue: Dev/Tue: Dev or Asha/' rota.txt
$ git commit -am "Update rota"
[fix-3-tuesday 337fafd] Update rota
1 file changed, 1 insertion(+), 1 deletion(-)
$ cd ../maintainer
$ echo "Peas: row 3" >> plan.txt
$ git commit -am "Add peas"
[main 95a504b] Add peas
1 file changed, 1 insertion(+)
$ git push
To ../upstream.git
ff55e83..95a504b main -> main
$ cd ../my-copy
$ git fetch upstream
From ../upstream
* [new branch] main -> upstream/main
$ git log --oneline --graph --all
* 95a504b Add peas
| * 337fafd Update rota
|/
* ff55e83 Add plan, rota and contributing notes
Look at the graph. The original has moved ahead, and Asha’s commit still hangs from the older point. If she opened a pull request now, the maintainer would have to deal with a change built on old ground. Better to check first.
Audit before you ask
Most projects write down what they expect from contributors. A script cannot read every rule, but it can check the common ones, and doing so saves reviewers’ time. The audit below tests eight things against the real repository. The size limit and the branch name pattern are made-up teaching rules. In a real project you would use whatever its contributing notes say.
import re, subprocess
REPO = "/home/nia/my-copy"
def git(*a):
return subprocess.run(["git", "-C", REPO, *a], capture_output=True, text=True).stdout.strip()
branch = git("branch", "--show-current")
subjects = git("log", "--format=%s", "upstream/main..HEAD").splitlines()
def tidy(m):
return len(m) <= 50 and not m.endswith(".") and m[0].isupper() and m.split()[0].lower() not in {"update", "fix", "wip", "stuff"}
stat = [l.split("\t") for l in git("diff", "--numstat", "upstream/main...HEAD").splitlines()]
changed = sum(int(a) + int(r) for a, r, f in stat)
results = []
def check(name, ok, detail):
results.append(ok)
print(("PASS " if ok else "FAIL ") + name + ": " + detail)
check("branch name", bool(re.fullmatch(r"(fix|add)-\d+-[a-z-]+", branch)), branch)
check("not working on main", branch != "main", "on " + branch)
check("tidy commit titles", all(tidy(m) for m in subjects), str(sum(tidy(m) for m in subjects)) + " of " + str(len(subjects)))
check("names an issue", any(re.search(r"(?i)\b(fixes|closes|resolves) #\d+", m) for m in subjects), "closing keyword found" if any(re.search(r"(?i)\b(fixes|closes|resolves) #\d+", m) for m in subjects) else "none")
behind = git("rev-list", "--count", "HEAD..upstream/main")
check("up to date with upstream", behind == "0", behind + " commits behind")
check("small change", changed <= 30 and len(stat) <= 3, str(len(stat)) + " files, " + str(changed) + " lines")
secrets = [f for a, r, f in stat if re.search(r"\.env|\.pem|secret", f)]
check("no secret-looking files", not secrets, str(len(secrets)) + " found")
pushed = git("rev-parse", "--verify", "-q", "origin/" + branch) == git("rev-parse", "HEAD")
check("pushed to my fork", pushed, "fork matches" if pushed else "fork is missing this work")
print("checks passed:", sum(results), "of", len(results))
PASS branch name: fix-3-tuesday
PASS not working on main: on fix-3-tuesday
FAIL tidy commit titles: 0 of 1
FAIL names an issue: none
FAIL up to date with upstream: 1 commits behind
PASS small change: 1 files, 2 lines
PASS no secret-looking files: 0 found
FAIL pushed to my fork: fork is missing this work
checks passed: 4 of 8
The contribution passed 4 of 8 checks. The failures were tidy commit titles, names an issue, up to date with upstream and pushed to my fork. All four are fixable in a few commands, and each fix uses something from this course.
Fix and publish
- Titles and the issue: reword the latest commit with
git commit --amend, and add the closing word and number, as in lesson 12. - Out of date: rebase the branch onto
upstream/main, as in lesson 19. The branch is private to Asha, so rewriting it is safe. - Not pushed: push the branch to the fork, with
-uso the branch remembers where it goes.
$ git commit --amend -m "Add a Tuesday backup (fixes #3)"
[fix-3-tuesday 9354f80] Add a Tuesday backup (fixes #3)
Date: Mon Nov 2 09:17:00 2026 +0000
1 file changed, 1 insertion(+), 1 deletion(-)
$ git rebase upstream/main
Successfully rebased and updated refs/heads/fix-3-tuesday.
$ git push -u origin fix-3-tuesday
To /home/nia/fork.git
* [new branch] fix-3-tuesday -> fix-3-tuesday
branch 'fix-3-tuesday' set up to track 'origin/fix-3-tuesday'.
$ git log --oneline --graph --all
* c176a02 Add a Tuesday backup (fixes #3)
* 95a504b Add peas
* ff55e83 Add plan, rota and contributing notes
PASS branch name: fix-3-tuesday
PASS not working on main: on fix-3-tuesday
PASS tidy commit titles: 1 of 1
PASS names an issue: closing keyword found
PASS up to date with upstream: 0 commits behind
PASS small change: 1 files, 2 lines
PASS no secret-looking files: 0 found
PASS pushed to my fork: fork matches
checks passed: 8 of 8
Now the result is 8 of 8. The graph shows a straight line: the original’s newest commit, then Asha’s single clear commit on top. The fork has the same commit, so the pull request will show exactly one change.
Write the pull request
A good description saves a round trip of questions. The short program below drafts the text from the real history, so the title and the change summary are always accurate. The reason and the checking are written by the person, because no program knows them.
import subprocess
def git(*a):
return subprocess.run(["git", "-C", "/home/nia/my-copy", *a], capture_output=True, text=True).stdout.strip()
title = git("log", "-1", "--format=%s")
files = git("diff", "--stat", "upstream/main...HEAD").splitlines()[-1].strip()
print("Title:", title)
print("")
print("What changed:", files)
print("Why: the Tuesday rota had no backup volunteer.")
print("How I checked: read the diff and opened rota.txt.")
print("Closes #3")
Title: Add a Tuesday backup (fixes #3)
What changed: 1 file changed, 1 insertion(+), 1 deletion(-)
Why: the Tuesday rota had no backup volunteer.
How I checked: read the diff and opened rota.txt.
Closes #3
On GitHub, Asha would open the pull request from her branch on her fork to the original’s main, paste that text, and wait. These steps are a pattern, and the screens and settings change over time, so follow GitHub’s current help. Then comes the human part: answering questions politely, making requested changes as new commits, and being patient.
Take it further: your portfolio
You now have enough to build the portfolio from lesson 16: a small site in a repository of your own, published from a branch, with a README, a few issues, tagged versions, and a record of contributions. A visitor who opens it sees a history, and the history is the proof of your habits.
What this does and does not show
Eight of eight means the contribution meets the rules written in the audit. It was tested only on this made-up project, no real maintainer reviewed it, and no real pull request was opened. A real project may have different rules, and a real maintainer may ask for more. Use the audit idea as a checklist, not as a guarantee.
Opening a pull request without reading the project’s contributing notes. Many projects have a template, a style guide, or a rule about discussing big changes first. Reading them costs minutes and saves everyone’s time.
The project, people, issue and rules are made up, and no real GitHub pull request was opened. The audit rules, including the size limit and the branch name pattern, are teaching examples. Features and wording on GitHub change over time, so check its help pages.
Practice for this lesson
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
Why make a branch for a contribution?
- It keeps one change separate and your fork’s main clean
- Git requires it
- Branches are faster to type
- The maintainer cannot see main
Asha used fix-3-tuesday.
Why was the first audit failing the up to date check?
- Her branch was empty
- The original had a new commit that her branch did not include
- Her fork was deleted
- The file was too large
She was one commit behind upstream.
Which command fixed the commit message?
- git push –force
- git stash
- git tag
- git commit –amend
The latest commit was private to Asha, so amending was safe.
Why was rebasing her branch safe here?
- Rebase never changes anything
- Nobody else had her commits yet
- The remote does not exist
- It was main
The golden rule only protects commits others already have.
What does passing every check in the audit prove?
- The maintainer will merge it
- The change is perfect
- GitHub has approved it
- It meets the rules written in the audit, not that a maintainer will accept it
A real review is still needed.
Summary
- A contribution is one small, named change on its own branch, based on the latest original.
- Check your work against the project rules before asking for a review.
- Amend and rebase are safe on private commits; push the branch to your fork.
- Draft the pull request from real history, and write the reason yourself.
Questions
Do I need a real project to practise?
No. You can build the whole loop with an upstream, a fork and a clone in a scratch folder, as this lesson did. When you feel ready, find a small project that welcomes contributions.
What if the maintainer asks for changes?
Make them on the same branch as new commits, or amend if your team prefers, and push again. The pull request updates itself.
How small should a first contribution be?
Very small: a typo, a missing line in the docs, or a clear bug. Small changes get reviewed quickly and teach you the project's habits.
