Content from Introduction

Last updated on 2025-07-15 | Edit this page

Estimated time: 10 minutes

Overview

Questions

  • What are Pull Requests (PRs)?
  • How do PRs help with software development?

Objectives

  • Become familiar with the purpose of PRs.

What are Pull Requests?

To borrow from Rachel Garner, “Software developers use pull requests, otherwise known as PR, to initiate the process of integrating new code changes into the main project repository. Pull requests are sent through git systems, like GitLab, GitHub, and BitBucket, to notify the rest of your team that a branch or fork is ready to be reviewed.”

Decorative image from Undraw.co to visualize a version control pipeline

In other words, PRs are a mechanism for introducing and merging changes into a code base in a manner that enables discussion and collaboration.

In this lesson, students will learn about better practices for GitHub PRs.

How Pull Requests Fit in the Development Process

From Freira et al.: Visualization of the GitHub development workflow with PRs. Workflow goes from Developer to Clone to Create a Branch to individual commits to Create Pull Request to Discussion/Project Community, ending with Merge or close the PR

The development workflow can have several different formats; however, a simple one is this:

  1. Create a feature branch
  2. Make changes and commit back to the feature branch
  3. Open a Pull request

The Benefits of Pull Requests

Integrating PRs into the development process has numerous benefits. Some of the main ones are:

  • Collaboration: Pull requests provide a location for other developers to see and comment on proposed changes. This encourages collaboration and discussion.
  • Reduce risks: Other team members are able to review proposed changes and make suggestions, find potential risks, etc.
  • Improve quality: No one person knows better than a group. Using PRs allows a crowd to get involved and improve the quality of the code.

GitHub Pull Requests

Numerous different merging systems exist - both commercial and open-source, integrated and stand-alone.

GitHub integrates branching and merging into their version control system. Every project on GitHub can use the integrated pull requests feature.

INTERSECT training repository navigation bar, showing, from left to right: Code, Issues, Pull Requests, Actions, Projects, Security, Insights

To access a repository’s PRs, simply navigate to the repository root page and click on “Pull requests” in the navigation bar. This will take you to the page of all “Open” PRs.

Click on a PR to open it and see its details, plus any discussion.

Browsing Open PRs

Navigate to https://github.com/spack/spack and find the pull requests page.

  • How many PRs are currently open?
  • How many have been closed?
  • Who is the author of the top-most PR?

Key Points

  • Pull Requests are a way to control the introduction of new content into a shared repository.
  • Pull Requests enable better collaboration for multiple developers.

Content from Basic Pull Requests

Last updated on 2025-07-15 | Edit this page

Estimated time: 15 minutes

Overview

Questions

  • How do you open a PR?
  • How do you interact with a PR?
  • How do you merge a PR?

Objectives

  • Become familiar with basic actions on GitHub Pull Requests.

Open a PR

A PR cannot be opened without some changes to be incorporated. For this example, we will use the branch and merge workflow; however, another common method is the fork, branch, and merge method.

Multiple Paths Available

We will do the rest of this lesson through the GUI; however, all of these steps can be done via command line and your preferred text editor. Do whatever feels right for you!

Make a Change

First we will make a change to a file in our repository. We click on the preferred file in the repository and hit the “Edit” pencil in the top-right corner.

On a README file, the File edit button in the top-right is highlighted

Once the file is edited to our satisfaction, we click “Commit changes…”, which pops up a dialog box asking us to fill in the commit message.

Commit changes pop-up dialog with the sections Commit message, Extended commit message, and the radio option for "Commit directly to `main`" or "Create a new branch" circled

Rather than committing directly to the main branch, we will instead make a new branch with the changes.

Commit changes pop-up dialog, zoomed in on the "Create a new branch" radio button when clicked, which defaults a branch name that can be changed

GitHub will autopopulate a branch name for us. We can choose to keep it or change it.

Make a PR

Once we click “Commit changes,” the page will load the “Open a pull request” page with our commit message as the title.

Open a pull request page loaded - shows the commit message from the previous step as the Title, empty "Write" section

A new PR has several parts:

  • Title: This will display on the main “Pull request” page.
  • Write: This is an open area for the details of the PR. GitHub support Markdown formatting.
  • Preview: This will preview the Markdown-rendered version of the details.

To open the issue, click the “Create pull request” button.

Newly opened PR with proposed changes - main page shows the Title, description, list of commits, and merge options

Open a New PR

Navigate to your practice repository.

  • Make a change to your README.md file
  • Commit the changes to a new branch
  • Put a basic title and details
  • Create the PR

Interact with a PR

There are many interactions available on an open PR.

The most basic interaction is adding a comment. This is how you can interact with the PR author, the assignee, and others who have commented on or subscribed to the PR.

Simply click in the comment box at the bottom of the PR, type whatever you’d like, and click “Comment.”

Comment box on a Pull Request - Write section includes a statement, "I am writing a comment on this PR"

Another useful feature for GitHub is linking Issues and PRs. This is actually very simple. In the PR’s description or in a comment, mention the relevant Issue using # and the Issue number.

An image using the pound symbol (#) to pop-up options for linking other Issues or Pull Requests

This will create a link to the Issue.

An image showing the pop-up to a linked issue. The pop-up shows a small preview of the linked issue that includes the title and some portion of the description.

You can also edit the information in the right-hand column.

Information block on the right-hand side that includes reviewers, assignees, labels, projects

We will cover the following options:

Options Purpose
Reviewers Assign reviewer(s) to look over your proposed changes.
Assignees Add assignee(s) who are responsible for incorporating proposed changes.
Labels Assign label(s) to categorize the PR.

Assignment Time

Navigate to your PR from the previous exercise.

  • Add yourself as the Assignee
  • Mention one of your open Issues

Merge a PR

We are done with these changes. We have completed the work on it, had our discussion, and now we are ready to merge the changes.

Wait, what about review?

Nobody reviewed our changes, so do we really want to merge? In a real-case scenario, no! We will cover more about reviewing later, though, so we are going to skip it for now.

Merging a PR is quite simple - just click the “Merge pull request” button.

The merge options on the example PR that shows that the branch has no conflicts and the "Merge pull request" button highlighted

The dropdown on the “Merge pull request” shows several options:

Merge PR dropdown with three options - Create a merge commit, Squash and merge, Rebase and merge

We will not cover all of these options here, but read more about them in GitHub’s official documentation.

When you click the “Merge pull request” button, a new dialog box appears, prompting for the commit message. Once you have made the preferred edits, click “Confirm merge.”

Confirm merge dialog box - shows the merge commit message, an extended message, and a button to confirm the merge

The changes have been incorporated back into the main branch.

Time to Merge

Navigate to your PR from the previous exercises.

  • Click “Merge pull request”
  • Modify the merge message
  • Merge!

You now know the basic actions you can take on a GitHub Pull Request!

Key Points

  • New PRs can be opened in a repository from a branch or a fork.
  • Text on PRs use Markdown styling for formatting.
  • A user can interact with PRs in multiple ways: commenting, assigning reviewers, linking to other issues and pull requests, and more.

Content from Labels and Templates

Last updated on 2025-07-15 | Edit this page

Estimated time: 15 minutes

Overview

Questions

  • How do you assign labels to PRs?
  • How do you create PR templates?

Objectives

  • Learn how to use labels for GitHub PRs.
  • Learn how to create a PR template.

GitHub Labels

Each new GitHub repository comes with a set of default labels that can be assigned to issues, pull requests, or discussions.

From GitHub’s official documentation:

Label Description
bug Indicates an unexpected problem or unintended behavior
documentation Indicates a need for improvements or additions to documentation
duplicate Indicates similar issues, pull requests, or discussions
enhancement Indicates new feature requests
good first issue Indicates a good issue for first-time contributors
help wanted Indicates that a maintainer wants help on an issue or pull request
invalid Indicates that an issue, pull request, or discussion is no longer relevant
question Indicates that an issue, pull request, or discussion needs more information
wontfix Indicates that work won’t continue on an issue, pull request, or discussion

These labels can be viewed from the Issues and Pull Requests pages.

The PR page with the labels option ("Labels - 9") highlighted

Using Labels

Labels can be applied from the main Pull requests page or within a single PR.

From the main Pull requests page, simply checkmark the PR, hit the “Label” dropdown, select your preferred label(s), and click outside of the dropdown.

Display of the "Apply Labels" dropdown from the main Pull requests page - shows all of the label colors and names

To apply within a single PR, click on the PR to open it. Then you will see the “Labels” option on the right-hand side.

Click on “Labels”. A dropdown will appear in which you can select or deselect your preferred label(s).

Cog-wheel option selected to reveal the label dropdown within a single pull request

Stick the Label

Navigate to your practice repository’s PR page.

  • Make another small change to your README.md and open a PR
  • Add the documentation label

What are PR Templates?

PR templates in GitHub are a way to pre-fill new PRs with specific sections, data, instructions, etc.

They are customizable for every project. You can add as many templates as makes sense for your project, or you can have none at all.

Create a New PR Template

Unlike Issues, GitHub does not have a default template for PRs. Instead, we must make the template from scratch.

We navigate to the main repository page. We can make the template in the root of the repository; however, we recommend instead making it in the .github directory.

The .github Directory

If you are completing this episode after doing the Issue Tracking lesson, you should already have a .github directory. If not, you’ll need to make one! Read more about it on freeCodeCamp.

In the .github repository, we will add a new file named PULL_REQUEST_TEMPLATE.md.

Through the GitHub GUI, "Add file" button selected, with "Create new file" highlighted, within the .github directory

You can now put whatever content you desire in the template. Some examples are:

  • Link to Issue: If you want the submitter to link to relevant issues.
  • Summary: A section for a description of the changes proposed
  • Checklists: A checklist of steps to be completed before a PR can be reviewed.
  • Legal Acknowledgement: A summary of legal information

Once the template has the preferred information, commit the changes to the main branch.

Make that Template

Navigate to your practice repository’s PR page. Create a PR Template that includes:

  • Description
  • Checklist with two steps
  • (CHALLENGE) Add a comment that does not render in Markdown to provide extra information for the submitter

Now when a new PR is opened, the “Write” section will autofill with our template.

{alt=‘New PR with the template above - default Title, Write section includes “Description”, checklist, and extra Markdown comment that won’t render in the preview’}

Key Points

  • Labelling PRs can help with prioritization and organization.
  • PR Templates can provide clear instructions for steps, expectations, and more.

Content from 'Good' Pull Requests

Last updated on 2025-07-15 | Edit this page

Estimated time: 5 minutes

Overview

Questions

  • What does it mean to be a ‘good’ PR?
  • What should you do to make a ‘good’ PR?

Objectives

  • Become familiar with what makes a ‘good’ PR.

What makes a ‘Good’ Pull request?

Now that we are familiar with the basic makeup of a pull request, we want to address the question, “What makes a good pull request?”

There are many answers to this question, and, like anything, there is no single right answer, but here are some useful tips.

The Single Responsibility Principle

One of the SOLID principles, the Single Responsibility Principle says, “A module should be responsible to one, and only one, actor.” This principle also applies for pull requests.

When making changes and getting ready to submit a PR, the changes within that PR should all be related and, ideally, doing one clear thing.

This will make it easier to review and to ensure that changes don’t introduce new, seemingly “unrelated” bugs.

Do one thing, and one thing only

If your PR has many unrelated changes together, separate it into multiple different PRs.

Reasonable Size

Have you ever been assigned to review a PR with several hundreds or thousands of line changes? These are monstrous, difficult to review, and can take much longer to merge back into the code base.

Keep your PRs a reasonable size! Some changes are, in fact, just big; however, if you can, split big changes into several smaller PRs to increase the reviewability and make discussions more productive.

Break it down

If your PR is very large, split it into smaller PRs.

Be Descriptive

When making your PR, be descriptive in the title and description. Include the answers to common questions:

  1. What is being changed?
  2. How did it change (and what other effects might there be)?
  3. Why is this change being suggested?

Putting the answer to these questions in the description section of the PR will make it clear the motivation and give a higher level overview for reviewers so they know more about the suggested changes.

What, How, Why

Preemptively answer common questions in the description of your PR to streamline the review process.

Key Points

  • A pull request should contain ONE cohesive change.
  • A pull request should, ideally, be quickly reviewable.
  • A pull request description should give an overview of what, how, and why something changed.

Content from Code Reviews

Last updated on 2025-07-15 | Edit this page

Estimated time: 15 minutes

Overview

Questions

  • How do you add reviews to a PR?
  • How do you address requested changes?

Objectives

  • Become familiar with the code review process on GitHub.

Request a Review

Requesting a review can be done within a PR. Click on a PR, then click on “Reviewers” on the right-hand side. Here you can type in and select reviewers for your PR.

Reviewers menu on a Pull Request - includes the text "Select up to 15 reviewers" and a search bar in which a user can start type a GitHub handle

No reviewers?

At this point, likely no reviewers will appear. You can only directly request reviews from “Collaborators” on your repository.

Add a Review

To add a review to a PR, navigate to the PR in question and click on “Files changed.”

The Pull Request main page with the "Files Changed" tab (far-right option) circled

Within this page, when you hover over a line of text, a + button will appear to the left.

Small example of what the plus (+) symbol looks like for adding comments to a specific line on a PR

Click on the + button to add a comment to that line.

The pop-up dialog to add a comment on Line 6 - includes a Write and Preview section plus buttons to Cancel, Add single comment, and Start a review

At this point, you can “Cancel”, “Add single comment”, or “Start a review.” If you click “Add single comment”, the comment will be added without rendering a review decision. If you click “Start a review”, this will “start” a review.

Can you see it yet?

At this point, no one can see your review. It is “Pending” until you finish all of your comments.

Once you have finished adding all of the comments, you will need to press the “Review changes” button.

Files changed page with review button highlighted

You will see three options: “Comment”, “Approve”, or “Request changes.”

Greyed out options?

Are you following along on your own PR? You might notice that you cannot approve or request changes. This is because you are the author! GitHub doesn’t allow authors to do either of these actions.

Let’s Review

Partner up with another participant and navigate to their practice repository. Add a few comments to one of their PRs and submit the review, requesting changes.

Address a Review

Review comments can be viewed in the “Conversation” tab as well as in the “Files changed” tab.

An image displaying the main Pull request page (Conversation), on which the review comments appear lumped together with a preview of each line/comment in its own box
An image displaying the Files changed page, on which the review comments appear on each line on which they were added

Incorporating requested changes can be done via command line or through the GitHub GUI. Once addressed and pushed, you can resolved the different conversations and re-request a review.

Fix It

Address the changes your partner requested and re-request a review from them.

And that’s all, folks! You now know much more about GitHub Pull Requests.

Key Points

  • Code reviews are integrated into GitHub Pull requests.
  • Reviewers can approve, request changes, or simply add comments as part of the review process.