How to make your first Pull Request on GitHub

Many tutorials exist about this topic but they make things overly complicated by assuming you have to contribute code to a project. So there’s all the git setup before that.

What if you just need to edit a file, maybe the project README to fix a typo?

You don’t need to know how to code or how to use Git to do that. But once you start doing Pull Requests, you can do many more things and collaborate on projects with other people! And maybe this will push you to also contribute code later on.

I assume you already have a (free) GitHub account. If you don’t, then go to github.com and get one.

Let me show you the process.

I made this PR in 2019, and the screenshots are from that time. GitHub’s editor looks different today and some buttons have new names, so I’ll point out what to click now as we go.

I went to this page https://web.dev/articles/prefers-color-scheme and I found a possible typo. This line is missing a dot at the end.

I’m not a grammar nazi, this is just for the sake of finding an example 😄

I know that site is hosted on GitHub, and that exact article is hosted here: https://github.com/GoogleChrome/web.dev/tree/main/src/site/content/en/blog/prefers-color-scheme

The web.dev repository is archived now, which means it’s read-only and doesn’t accept pull requests anymore. To follow along, pick an active project you use. A typo in a README is a perfect first PR.

I open the index.md file https://github.com/GoogleChrome/web.dev/blob/main/src/site/content/en/blog/prefers-color-scheme/index.md directly on GitHub and I press the pencil icon in the file toolbar. Back then, hovering it said “Fork this project and edit the file”.

Today the pencil icon opens a page with a Fork this repository button. Click it and GitHub creates your own copy of the project, called a fork.

Then GitHub opens the editor. Mine showed this message:

You’re editing a file in a project you don’t have write access to. Submitting a change to this file will write it to a new branch in your fork flaviocopes/web.dev, so you can send a pull request.

I can go and add that dot, then at the form at the bottom I explain the changes I made:

I pressed the “Propose File Change” button and a compare view showed up.

Today’s editor has no form at the bottom. You make your edit, click Preview if you want to check it, then click Commit changes… above the file. A dialog asks for a short commit message that explains the change. Click Propose changes and the compare view shows up.

There I can review the changes I made, to make sure all is fine, and finally I can click the Create pull request button. At this point the changes live in your fork of the project, the copy GitHub made when you clicked Fork this repository.

At the top of this view you can see that I’m about to submit a PR to the GoogleChrome/web.dev project from my fork flaviocopes/web.dev, from my branch patch-2 to their master branch. Most projects call that branch main today, web.dev included.

Pressing the Create pull request button shows another form where I can write a title and a detailed description for the Pull Request.

Pull Requests can contain many different changes. In theory you could have lots of files edited in the same PR, and that’s why you can add a summary.

This repository has a template for the PR text, to help the team manage it. Our PR is very simple so I remove the template and just paste the content from the commit message from before.

Notice the hint on the right? They tell me the project has a CONTRIBUTING.md file, which explains how to contribute and the guidelines. Pretty cool.

Seems we need to sign a CLA (Contributor License Agreement) to complete our PR. I already signed a Google CLA in the past so this step is clear for me, but you might need to fix that. Most projects don’t really need it.

I clicked Create pull request and the PR is now sent!

Now it’s up to the project maintainers to step in and accept it, you just need to wait for an email telling you that it’s been merged, or any comments other people had.

[… a couple hours passed by…]

I got an email back, the PR was rejected because that dot was actually in the correct place! (I didn’t know that).

But anyway here’s a thing I wanted to add: don’t be angry or upset if a PR you submit is not accepted. The maintainers of the project work on it for months or years and they know better than you about what’s better for it.

Plus, especially with code, views might be very very different and a PR you think is great might not be welcome.

It’s also best to ask before working on a substantial PR, to see if it’s something the project actually needs.

But this is a topic on its own.

Want me to talk about your product? You can sponsor this site.