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. 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

Once you've pushed your changes to your fork, and you're ready to submit them to the project, open your browser and navigate to your forked repo.

If you've just pushed for the first time, you'll see a line at the top stating, "You've recently pushed branches:" and a bar below it containing your branch name and a Compare & pull request button.

If you pushed multiple times from the same branch in a short period of time, or for some other reason the Compare & pull request button doesn't show up, you can create it manually.

Click on the dropdown menu for Branch:

Find your branch name in the menu.

Then click the New pull request button.

If you still don't see the Pull Request button

Check that GitHub is registering that you have a commit ready (orange circle). This one does. So click on the Contribute Button (purple circle):

Then in the dropdown click on the Open Pull Request button:

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

Filling out the Pull Request

Let's break it down!

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.

The next section is where you'll enter your pull request message. First read the text that Adafruit has put for Adafruit Learning System PRs.

As I'm working on a defined project, I have added text describing what I have done.

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.

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

The last section shows you your changes. Like git diff, it will show you only the code surrounding your changes. 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.

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, you'll find the Create a pull request button. Click it to create your pull request.

You've created your pull request! 

The next section will cover what happens during the open pull request.

If the CI Fails to Start

If the GitHub Actions CI fails to process your PR, here is a simple way to trigger it. Go into your commit, edit one of the files ever so slightly - add a space (or delete one not needed) and it should trigger the CI to reexamine the PR again.

Note for Python files, do not add trailing spaces to a line, that will trigger an error.