Content from Introduction
Last updated on 2024-06-27 | Edit this page
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.”
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
The development workflow can have several different formats; however, a simple one is this:
- Create a feature branch
- Make changes and commit back to the feature branch
- 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.
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 2024-06-27 | Edit this page
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.
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.
Rather than committing directly to the main branch, we will instead make a new branch with the changes.
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.
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.
Open a New PR
Navigate to your practice repository.
- Make a change to your
README.mdfile - 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.”
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.
This will create a link to the Issue.
You can also edit the information in the right-hand column.
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 dropdown on the “Merge pull request” shows several options:
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.”
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 2024-06-27 | Edit this page
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.
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.
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).
Stick the Label
Navigate to your practice repository’s PR page.
- Make another small change to your
README.mdand open a PR - Add the
documentationlabel
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.
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.
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 2024-06-27 | Edit this page
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:
- What is being changed?
- How did it change (and what other effects might there be)?
- 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 2024-06-27 | Edit this page
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.
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.”
Within this page, when you hover over a line of text, a
+ button will appear to the left.
Click on the + button to add a comment to that line.
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.
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.
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.”