How to Contribute to Open Source: Forks and Pull Requests

You cannot push to someone else's repository. To contribute, you make your own copy on GitHub, change that, and ask the original project to accept your work.

Fork or clone?#

For an open source contribution you do both: fork it, then clone your fork.

original/project   -- Fork -->   your-name/project
(upstream)                       (origin)
      ^                               |
      |                               | git clone
      |                               v
      +----- pull request ------  your computer

Step 1: Fork and clone#

On the project's GitHub page, click Fork, then Create fork. Clone your fork. In this example the address of the fork ends in my-fork.git:

git clone -q https://github.com/your-name/my-fork.git
cd my-fork

Step 2: Add the original as upstream#

origin points to your fork. Add a second remote for the original, called upstream by convention. Yours would be an address like https://github.com/original-owner/project.git:

git remote add upstream https://github.com/your-name/project.git
git remote -v

origin	https://github.com/your-name/my-fork.git (fetch)
origin	https://github.com/your-name/my-fork.git (push)
upstream	https://github.com/your-name/project.git (fetch)
upstream	https://github.com/your-name/project.git (push)

Step 3: Work on a branch#

Never work on your fork's main. Keep it as a clean copy of the original.

git switch -c fix-readme-typo
echo "A useful library for dates" > README.md
git commit -q -am "Fix description in README"
git push -q -u origin fix-readme-typo
git branch -a

Switched to a new branch 'fix-readme-typo'
* fix-readme-typo
  main
  remotes/origin/HEAD -> origin/main
  remotes/origin/fix-readme-typo
  remotes/origin/main

Step 4: Open the pull request#

On GitHub, a banner on your fork offers Compare & pull request. Check that the base repository is the original project and the head repository is your fork. Describe the change and create the PR. Maintainers may ask for changes; push them to the same branch.

Step 5: Keep your fork up to date#

The original project moves on while you work. Update your main from upstream:

git switch -q main
git fetch -q upstream
git merge upstream/main
git push -q origin main
git log --oneline

Updating 6ec0b28..8a959d9
Fast-forward
 docs.txt | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs.txt
8a959d9 Add docs
6ec0b28 Start project

GitHub also has a Sync fork button on your fork's page, which does the same thing online.

Finding something to work on#

• Start with projects you already use. You understand what they are for.
• Search GitHub for issues labelled good first issue or help wanted.
• Documentation fixes are real contributions, and a good way to learn a project's process.

How to be a welcome contributor#

1. Read README.md and CONTRIBUTING.md first. Many projects have their own rules.
2. Check that nobody else is working on the issue, and comment before starting something big.
3. Keep your change small and focused on one problem.
4. Run the project's tests before you push.
5. Be patient and polite. Maintainers are often volunteers.

Common mistakes#

Practice#

git remote get-url upstream
git rev-list --count upstream/main..main

https://github.com/your-name/project.git
0

Key takeaway#

Next: Writing Good Commits.