Your first pull request

A pull request, usually shortened to PR, is a polite proposal: "here is a change I made on my copy of your project; would you like to pull it into yours?" It is the standard way strangers contribute to open source, and the whole workflow exists to protect one thing, the maintainers' attention. You do not have permission to write to their repository, so you work on your own copy, and they decide whether to accept what you send. This lesson walks through the full path once, then covers the human side, which is where first-timers usually stumble.

Pick something small on purpose

Your first PR is not the place for a new feature. It is a rehearsal for the process, so make the change as small as it can be while still being useful. Good entry points:

• Documentation fixes: a typo, an outdated command, a broken link, an unclear sentence. Docs are read by every newcomer, so errors in them cost the most, and maintainers generally welcome tidy fixes.
• Missing or wrong build notes: the failed step you wrote down in lesson 3.
• Small bugs with a clear reproduction, ideally with a failing test you can make pass.
• Issues the maintainers have labelled for newcomers. Many projects use labels such as good first issue or help wanted for this. Not every project does, so look at what labels exist and read CONTRIBUTING.

Before starting work on an issue, read the comments. If someone is already working on it, or the maintainers have said they do not want it, you will save yourself a wasted evening. If it is unclaimed, leave a short comment saying you would like to take it.

The workflow, step by step

1. Fork. On the hosting site, press the fork button. This creates your own copy of the repository under your account. You can write to it freely.

2. Clone your fork. Download your copy to your computer.

git clone https://github.com/your-name/project.git
cd project

3. Add the original as upstream. This lets you pull in new work from the real project later.

git remote add upstream https://github.com/original-owner/project.git
git remote -v

Your fork is conventionally named origin, and the original project upstream. If this naming confuses you, git remote -v shows exactly where each name points.

4. Sync, then branch. Make sure you start from the current state of the project, and never work directly on main.

git switch main
git pull upstream main
git switch -c fix-wiring-doc-typo

Use a branch name that says what the change is. Keeping main clean means your fork can always be updated from upstream without conflicts.

5. Make the change. Edit only what you need. Resist fixing three other things you noticed on the way; each deserves its own PR. A small, focused diff is the single biggest factor in how quickly a PR is reviewed.

6. Run the tests and checks. Use the build and test commands from lesson 3, plus any linter or formatter the project asks for. Reviewers are far more patient with a PR that already passes than with one that makes them run it to discover it fails.

7. Commit well. One logical change, with a message in the project's style, using the habits from lesson 2.

git status
git add docs/wiring.md
git commit -m "Fix wrong pin name in wiring guide"

8. Push your branch to your fork.

git push -u origin fix-wiring-doc-typo

9. Open the pull request. The hosting site will usually show a banner offering to open one from your freshly pushed branch. If you use the GitHub command line tool, gh pr create does the same from the terminal. Aim the PR at the main branch (or whichever branch CONTRIBUTING names) of the original repository.

Writing the PR description

A reviewer opens your PR cold, with no idea what you were thinking. The description is your chance to remove every question before it is asked. Cover:

• What changed, in one or two sentences.
• Why: the problem or the issue it addresses. Link the issue so it closes automatically when merged, if the project uses that convention.
• How you tested it: the exact commands you ran and, for hardware code, what board you tried it on.
• Anything you are unsure about. Honest uncertainty is welcome; it tells the reviewer where to look.

If the project provides a PR template, fill in every section rather than deleting it.

Review etiquette

Review is a conversation between people who both want the project to be good. A few principles make it go smoothly.

Be patient. Maintainers have jobs, families and other pull requests. Days or weeks without a reply is common in volunteer projects. If there is truly no response after a long time, one polite nudge is fine. Repeated pinging is not.

Assume good faith. Feedback is about the code, not about you. A request for changes is not a rejection; it is the normal path to acceptance. Even experienced engineers get requests on nearly every PR they send.

Respond to every comment. Either make the change and say so, or explain your reasoning politely if you disagree. If you do not understand a request, ask a specific question.

Do not take it personally if it is declined. Sometimes a good change does not fit the direction of the project, or a maintainer simply disagrees. Thank them and move on. You still learned the process, and your fork keeps the work.

Handling feedback

When the reviewer asks for changes, you do not open a new PR. You edit on the same branch and push again, and the PR updates automatically.

# on your branch, after making the requested edits
git add docs/wiring.md
git commit -m "Clarify pin table as requested in review"
git push

Some projects will ask you to combine your commits into one before merging. This is a project preference, and they will tell you what they want and often how to do it. Follow their instructions rather than guessing at commands that rewrite history.

If the project has moved on while your PR waited, you may be asked to update it. Bring in the latest upstream work and resolve any conflicts, as in lesson 2.

git fetch upstream
git merge upstream/main
git push

When it is merged, delete your branch, sync your fork's main from upstream, and celebrate. You are now a contributor, and the second PR is always easier than the first.