-
-
Notifications
You must be signed in to change notification settings - Fork 17
How to Create Pull Requests
Creating a Pull Request (PR) is an essential step in the development process, allowing you to propose your changes and collaborate effectively with your team. Here's a simplified and cohesive guide to creating a new PR in our repository
A Pull Request, often just called a PR, is a request to pull a developer's code changes into the larger code base.
Because we don't want to allow just any code into our application, the Pull Request is where the developer will explain what changes were made and why they were made. When a developer is working on code, they are working on a copy that exists only on their computer and doesn't affect the live site. That code is kept up to date so we are able to seamlessly integrate new code.
PRs are also a great place for developers to share knowledge and learn from one another. Since it is impossible to know everything, a new set of eyes may be able to improve the proposed solution.
An effective PR will explain to a reviewer:
- what the original issue was on the site?
- what the actual issue was in the code?
- what changes the developer made?
- why they made those changes?
PRs help us track and understand the thought process and the context of the app at the time the changes were integrated.
There are two ways to open a new Pull Request:
- Open Pull Requests Tab: Navigate to the 'Pull Requests' tab on your GitHub repository page.
- Initiate New Pull Request: Click the "New pull request" button.
Github loves to add little hacks like this to make actions easier. For full details on using query parameters, see the github documentation here.
https://github.com/hackforla/expunge-assist/compare/dev...YOURBRANCH?quick_pull=1
The most important part of this URL is dev...YOURBRANCH. dev is the target branch. What branch are you requesting your changes be brought into? Unless you are the dev lead, or we are working off a feature branch, it will almost always be dev. YOURBRANCH is whatever branch contains the changes you are trying to merge into dev.
Regardless of how you open the PR, it's best practice to confirm your branches are pointed to the correct places.
-
Set Base Branch: Ensure that the base branch is set to
base:dev. - Set Compare Branch: Ensure that the compare branch is set to the local branch you created and are pushing the changes from.
This is the second most important part of the PR, behind the actual code. Ideally a reviewer, who has had nothing to do with this issue previously, would find all the context required to adequately review the code within the PR itself.
Create a concise and meaningful title for your PR, use the issue number in-front of your title like so: #411-fix footer this provides the reviewer with clear insight on what issue this PR is regarding.
First and most important, link the related issue to the pull request by adding Closes #ISSUE_NUMBER. Linking the issue allows us to trace the exact changes made, if a bug was introduced.
Next, add a detailed description of the changes. Explain why these changes are necessary and how they address the issue.
Eventually we'll have a template asking for these changes.
Pull Requests can feel like the end of the journey for a developer, and thus may not get the attention they deserve. You've solved the issue, now what? Pull requests are a great opportunity to not only learn from others, but also to put your best foot forward and make arguments for your code.
Before submitting, confirm that:
- the problem described in the issue is solved
- all the commits are related to the issue
- the code has been formatted/linted
- you are confident in your solution
PS. We now have a lint test on the PRs, so it will fail if your code is not formatted. Run the lint:fix command in the package.json before committing and pushing again to pass the test.
To get things moving, we have a couple logistical things we have to do.
- Add
ready for dev leadlabel to the PR - Move the associated issue to the
Ready for Reviewsection in our project board - Post in the
#expunge-assist-devchannel with a link to your newly created PR.
Peer reviews are not required, but appreciated! Conversation is an important part of pull requests.
Most of your reviews will likely come from the Development Lead. If the Lead requests changes, they will remove the ready for dev lead label. Review and make the changes requested. After pushing the requested changes, make sure the PR tests pass and add the ready for dev lead label again. Continue this fun cycle until the PR gets approval.
Once approved, your issue will be merged into dev and immediately merged into main and deployed.
Remember, a well-documented PR eases the review process and fosters better collaboration. Ensure your changes are clear, and don't hesitate to provide extra context where necessary! Happy coding!
The Wiki is a working document and we would love to improve it. Please compile any questions and suggestions you may have and submit it via GitHub. Here's information on how to create a GiHub issue.