Skip to content
Tutorials Center
My learning

Topics

Lesson 61 of 78 ยท GitHub and Platforms

Contributing to Open Source

A practical guide to your first open-source contribution: find a project, read CONTRIBUTING, fork and branch, write a clean pull request, handle review, and understand licenses and semver.

Open-source software is code that anyone may read, use, change and share under a license. Almost every tool you use is built this way, and contributing to it is one of the best ways to learn: you read real code, get feedback from experienced developers and build a public record of your work. It can also feel intimidating. Who may change what? What if the maintainers say no?

This lesson walks through the whole path: finding a project, reading its rules, making a change with the fork-and-branch workflow, writing a pull request that is easy to accept, dealing with feedback, and understanding licenses and version numbers. The sandbox has no network and no GitHub, so the platform steps are read-only, but the Git steps run for real against local repositories that play the roles of upstream, fork and clone.

How an open-source project works

Most projects have the same cast:

  • Maintainers decide what goes in. They have write access and are usually volunteers or a small team. Their time is the scarcest resource in the project.
  • Contributors propose changes (code, docs, tests, translations, bug reports). They do not have write access, so they work in their own copy.
  • Users use the software and sometimes report problems.

Contributions are not only code. A clearer error message, a fixed typo in the docs, a reproducible bug report or a reviewed pull request are all welcome and often more valuable than a big feature.

Finding a project

Start with software you already use. You know how it behaves and where it confuses people. Then look for these signals:

  • Recent activity. Commits and replies in the last few weeks.
  • Beginner labels. Issues tagged good first issue or help wanted (see Issues, Projects and Project Management).
  • A written contribution guide. CONTRIBUTING.md means maintainers expect and plan for newcomers.
  • A responsive community. Look at how maintainers treat other people's pull requests. Are they polite? Do they reply in days rather than months?

A project with a thousand open issues and no replies for a year is a poor first choice.

Read the rules first

Before you write a line, read these files in the repository root (or in .github/):

File What it tells you
README.md What the project is and how to build it
CONTRIBUTING.md How to propose changes: branches, tests, commit style, sign-off
CODE_OF_CONDUCT.md How people are expected to behave
LICENSE The terms under which your contribution will be shared
SECURITY.md How to report vulnerabilities privately (never in a public issue)
.github/PULL_REQUEST_TEMPLATE.md What a good pull request description contains

A typical CONTRIBUTING.md answers questions like these (read-only example):

TEXT
## Contributing

1. Open an issue first for anything bigger than a typo.
2. Fork the repository and create a branch from `main`.
3. Run `make test` and `make lint` before you push.
4. Use imperative commit messages ("Fix crash", not "Fixed crash").
5. Sign off your commits (`git commit -s`) to accept the DCO.
6. Keep pull requests focused: one change per PR.

Following these rules is the cheapest way to make a good impression. A pull request that ignores them is often closed without a review.

Code of conduct. It sets the tone for every interaction: be respectful, assume good intent, accept that maintainers may say no. Violations can get you banned, so treat it as part of the contribution guide.

The fork-and-branch workflow

You cannot push to a project you do not own. Instead:

  1. Fork the repository on the platform. This creates your own copy on the server (origin for you).
  2. Clone your fork to your computer.
  3. Add the original repository as a second remote, conventionally named upstream.
  4. Create a topic branch for your work. Never work on main of your fork.
  5. Commit, push to your fork, then open a pull request from your branch to the upstream repository.

This is the model described in Forks and Upstreams. Here is a complete run, with local bare repositories as the servers.

Bash Fork, clone, branch, push: the contributor workflow

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

At the end, the fork has two branches (main and your topic branch), and the pull request would contain exactly one commit: everything reachable from your branch but not from upstream/main. On GitHub you would now see a banner "Compare & pull request" on your fork. That is read-only, since there is no platform here.

Keeping your fork in sync

While your pull request waits, upstream moves on. Before you start new work (and before asking for a final review), bring your fork up to date: fetch upstream, then either rebase your branch on upstream/main or merge it, depending on the project's preference (check CONTRIBUTING.md).

Bash Update your branch after upstream moved on

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The "before" graph shows two lines of history that diverged from Add README. After the rebase, your commit sits on top of the upstream changelog commit, so the pull request is a clean, linear change. Because the rebase rewrote your commit, the normal git push is rejected (the example prints the rejected line, which says the update was not a fast-forward), and the fork's feature branch only shows the new history after the forced push; --force-with-lease is the safe way to overwrite your own branch (it refuses if someone else pushed to it). Never force-push to a shared branch. See Rebase for the details.

Making a good pull request

A pull request is a request for somebody else's time. Make it easy to say yes.

Keep it small and focused. One logical change per pull request. A 40-line fix gets reviewed in minutes; a 2,000-line "cleanup and feature" sits for weeks. If you notice an unrelated problem while working, make a separate PR.

Write a good title and description. The title says what in one line, like a commit subject. The description answers: What problem does this solve? How did you solve it? How did you test it? Link the issue with Fixes #123.

Write good commits. Imperative subject (โ‰ค 72 characters), a body that explains why. See Making Good Commits.

Run the tests and the linter first. Nothing annoys maintainers more than a pull request that fails the checks on the first run.

Add tests and docs when behaviour changes. A fix without a test is easy to break again.

Do not include noise. No reformatting of untouched code, no editor config files, no merge commits from syncing, no secrets.

Before you open a PR you can run a quick self-review. This script checks the things most reviewers notice first: whitespace errors, the size of the change and commit message length.

Bash A pre-pull-request self-check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The script finds trailing whitespace on the added line (git diff --check prints the file and line number), prints the diffstat, spots the leftover TODO and print( lines, and flags the commit subject that is too long and vague. In a real project you would fix these and amend the commit before opening the PR (see Amending and Filtering). Notice the three-dot form upstream-main...HEAD: it compares your branch against the merge base, so changes that only exist upstream do not show up as if you had removed them.

Dealing with review feedback

Review is a conversation, not a verdict. Expect comments on almost every pull request, including those from experienced contributors.

  • Assume good intent. Comments are about the code, not about you. Tone is hard to read in text.
  • Respond to every comment, even with "Done" or "Good point, fixed in abc1234".
  • Push fixes as new commits during review (or amend and force-push if the project prefers a clean history; ask). Reviewers can see what changed since their last look. Many projects squash commits on merge, so history inside the PR does not matter.
  • Ask when something is unclear. "I am not sure what you mean by X, do you mean Y?" is a good question.
  • Disagree politely and with evidence. If you think the suggestion is wrong, explain why. The maintainer owns the final decision.
  • Be patient. Maintainers are often volunteers. A gentle ping after a week or two is fine; daily pings are not.
  • Accept "no". Sometimes a change does not fit the project. That is not a failure; you learned the codebase and can often use your work in your own fork.

To apply review changes you add commits to the same branch and push again. The pull request updates itself.

Bash Address review feedback with a fixup commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

--fixup HEAD creates a commit named fixup! Add docs, which rebase --autosquash folds into the original commit. You could stop at the first log (two commits) if the project squashes on merge, or clean up as shown. Check what the project expects before rewriting history that reviewers have already seen.

Licenses in one page

Every open-source project has a license, which is the legal permission for others to use your code. Without a license, the default is "all rights reserved": nobody may legally use or modify it. When you contribute, your changes are normally offered under the project's license (many projects ask you to confirm this with a DCO sign-off or a CLA).

The main families:

Family Examples What it means
Permissive MIT, BSD-2/3, Apache-2.0 Use it for anything, including closed-source products. Keep the copyright notice. Apache-2.0 also grants patent rights.
Weak copyleft LGPL, MPL-2.0 Changes to the library itself must be shared, but programs that merely use it can stay closed.
Strong copyleft GPL-3.0, AGPL-3.0 Distributed modified versions (and, for the AGPL, network services) must be released under the same license.
Public domain-like CC0, Unlicense No restrictions.

This is a simplified map, not legal advice. For anything that matters (a company product, a dependency decision), read the actual license text or ask a lawyer. Two practical rules for contributors: do not paste in code whose license you do not know, and never copy code from a project with an incompatible license.

Many projects mark every file with a machine-readable SPDX identifier in a comment, for example // SPDX-License-Identifier: MIT. Tools can then audit licenses automatically.

Bash Audit SPDX license headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The audit shows two MIT files, one GPL-3.0-only file and one file with no header. A mix of MIT and GPL in one project is allowed, but combining them has consequences for the whole work, which is exactly the type of finding a license audit exists for. The missing header on orphan.c is the kind of gap a CI job can fail on.

Semantic versioning and changelogs

When maintainers cut a release, version numbers tell users how risky an upgrade is. Semantic Versioning (semver) uses three numbers, MAJOR.MINOR.PATCH:

  • PATCH (1.4.2 to 1.4.3): backwards-compatible bug fixes.
  • MINOR (1.4.3 to 1.5.0): new features that do not break existing users.
  • MAJOR (1.5.0 to 2.0.0): breaking changes.

Versions below 1.0.0 are "initial development" and may break at any time. Pre-releases look like 2.0.0-rc.1. Tags (see Tags) are the natural place to record a version: git tag v1.5.0.

A changelog (CHANGELOG.md) is a human-written list of notable changes per version, grouped as Added, Changed, Deprecated, Removed, Fixed and Security. If a project uses Conventional Commits, the commit types map onto the semver bump: fix: means patch, feat: means minor, and a ! after the type (or a BREAKING CHANGE: footer) means major.

Bash Compute the next version from commit messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

With one feat: among the commits, the function chooses a minor bump (v1.5.0). Once a commit with ! joins, the bump becomes major (v2.0.0), and the minor and patch numbers reset to zero. Real tools do the same, with more edge cases. See Project: Release Automation Script for a full version.

Your first contribution: a checklist

  1. Pick a project you use and read its CONTRIBUTING.md.
  2. Find a small issue (docs, a good first issue) or open one to propose your idea.
  3. Comment that you would like to work on it and wait for a reply on larger tasks.
  4. Fork, clone, add upstream, create a branch.
  5. Build the project and run the tests before changing anything, so you know what "green" looks like.
  6. Make the smallest change that solves the problem; add a test.
  7. Self-review the diff, then push to your fork and open the pull request with a clear description.
  8. Respond to feedback, stay polite, and say thanks when it is merged.

Documentation fixes are a respected first contribution. They teach you the whole workflow (fork, branch, pull request, review) at almost no risk, and every project needs them.

Check your understanding

Quick check ยท 6 questions

of 6 answered You scored / 6 ยท perfect!

  1. 1. Why do contributors usually work in a fork instead of cloning the project directly?

    Contributors normally lack write permission upstream. A fork gives them a repository they can push to, from which they open a pull request.
  2. 2. What is the conventional name for the remote that points at the original project?

    origin is your fork (where you cloned from); upstream is the original repository you sync from.
  3. 3. Which is the safest way to overwrite your own already-pushed topic branch after a rebase?

    --force-with-lease refuses to overwrite the remote branch if it contains commits you have not seen, which protects other people's work.
  4. 4. A project is at version 2.3.4. You fix a bug without changing behaviour that users rely on. Which version does semver suggest?

    Backwards-compatible bug fixes increase the PATCH number: 2.3.5.
  5. 5. What does an SPDX header such as SPDX-License-Identifier: MIT provide?

    SPDX identifiers are standard short names for licenses placed in file headers so that tools can list and check them automatically.
  6. 6. A maintainer asks for changes on your pull request. What is the best response?

    Pushing to the same branch updates the existing pull request, and replying to each comment keeps the discussion clear.

Summary

  • Contributing means proposing changes to a project you do not control: fork, clone, add upstream, branch, push to your fork, open a pull request.
  • Read README, CONTRIBUTING, CODE_OF_CONDUCT, LICENSE and SECURITY before you start.
  • Small, focused pull requests with a clear description, tests and clean commits get merged fastest.
  • Sync with git fetch upstream and rebase or merge; use --force-with-lease for your own rebased branches only.
  • Treat review as a conversation: respond to every comment, push fixes to the same branch, be patient and polite.
  • Licenses decide what others may do with code; SPDX headers make them auditable.
  • Semver (MAJOR.MINOR.PATCH) and a changelog tell users how risky an upgrade is.

Next: Fixing Common Git Mistakes