You've committed your changes and pushed them to your fork. You're ready to submit your changes to the original project for review. This means you're ready to put in a pull request.

A pull request, or PR, is exactly that: a request to pull your changes into the original project code. Basically, you're asking the owner of the original project to include your new changes. When changes are included in a project, it's called a merge. Completing a pull request involves merging the pull request into the original project.

A pull request isn't a single step, however. It's a process. You'll create your PR, submit any fixes necessary for the checks to pass, wait for review, submit any or discuss changes requested in the review, and then wait for your code to be merged into the project. Sometimes the review discussion might be quite involved. Not all PRs will be accepted. This is why it's important to submit a PR earlier rather than later so you can get feedback earlier on in the development process.

This section of the guide will cover creating your pull request. Let's get started!

Creating a Pull Request from Your push

Let's take one more look at the results of that last git push. Take a look at the highlighted section.

The highlighted section contains the following text, except with the applicable GitHub user ID, repository name, and branch name.

Create a pull request for 'your-branch-name' on GitHub by visiting:
     https://github.com/youruserID/Repo_Name/pull/new/your-branch-name

Create a pull request for 'your-branch-name' on GitHub by visiting:
     https://github.com/youruserID/Repo_Name/pull/new/your-branch-name

That's convenient! There are instructions and a URL are right in the push results. You can simply click on the link, or copy and paste it into your browser to get started.

There are plenty of situations where you will not create a pull request immediately after your first push to your fork. In those cases, you might not have that direct URL by the time you're ready to open your PR. Not a problem! You can also open a PR through GitHub.

Creating a Pull Request through GitHub

There are a couple of ways to create a pull request through GitHub, depending on how recently you pushed your code. If you pushed recently, you can create it from the original repository. If it's a bit, you'll want to create it from your fork.

Creating a PR from the Original Repository

Open your browser and navigate to the original repository, in this case, the Adafruit version of the library that you're contributing to. You'll see a box along the top with your username followed by your branch name, indicating that the branch had recent pushes. To create the PR, click the Compare & pull request button.

Creating a PR from Your Fork

Open your browser and navigate to your forked copy of the library you're contributing to. Above the file list, you'll see a dropdown that shows the main branch. Click on main.

From the resulting list, choose your branch name. Mine is f-strings-and-params.

The branch will now show your branch name, and you'll see a new section below it.  Click Contribute.

Click Open pull request.

Open a Pull Request

The next thing to do is open the pull request. The initial page will look something like this.

Let's break it down!

Automatic Merge Verification

The first section will let you know whether your request is able to be automatically merged. If it's not, that means someone else already made changes to the same section of code that you did, and you'll need to update your code to match the already existing changes before you can submit the pull request. It's possible to submit a PR that isn't able to be automatically merged, but often the owner of the project will ask you to update your code first anyway. So it's good practice to not submit until that section says Able to merge.

Pull Request Title and Message

The next section is where you'll enter your pull request message. Ideally you'll title it something that quickly describes what you changed. Then you can include more details in the message body. If you made a single commit, they may already be populated by your commit message. If you made multiple commits, it may simply be populated by your branch name. You can change them regardless if you'd like to be more descriptive.

Since I made multiple commits, it included only my branch name. So I've chosen to update it to include much more detailed information about my pull request.

Commit List

The next section includes your list of commits. The top details the number of commits, how many files were changed, and the number of contributors. I made two commits, changed one file, and am the sole contributor.

Your Changes

The last section shows you your changes. Like git diff, it will show you only the code surrounding your changes.

Above the changes are the number of files shown, and the total number of additions and deletions included in this change.

Then you'll see the name of the file you changed. The code you've added will show up in green. Any code you deleted will show up in red. Be aware, if you change an entire code block, it will show the original code in red, and your new code in green, even if you didn't remove the code contained within the block. This doesn't mean the code you changed was deleted! It's simply how the changes are shown here.

You can see here that I added the parameter descriptions, and updated the strings.

There are two ways to view changes on GitHub: unified view and split view. GitHub defaults to unified view, which is shown below. It shows the original and updated code in one column, very similar to git diff, which is very familiar to many folks. However, it can be a struggle for new folks to follow. That's where split view can help.

To switch to split view, click Split, found on the right side above the changes.

Split view shows you the original code in a column on the left, and the updated code in a column on the right. This may be easier for you to follow.

Once you pick a view, GitHub will remember your choice, and the next time you see changes, they'll be in whichever format you prefer.

Create Your Pull Request

Go through each of these sections and make sure they're all correct. Did you include all the commits you meant to? Do the changes show all of the changes you intended to make? Did you find a mistake? If you find anything you missed or need to change, back out of the pull request and finish up what you need to. Then start the process again.

If you're happy with everything you see, you're ready to open your pull request. Under where you entered your description, click the Create pull request button.

You've created your pull request! The next section will cover what happens during the open pull request. Let's take a look!