Introduction

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

Table of Contents

• Introduction
  • What is a Pull Request
  • What Makes a Good Pull Request
• Creating a New Pull Request
  • Opening a PR
    • Through the Github UI
    • Through URL Params
  • The Details
    • Confirm Branches
    • Adding the Title and Description
  • Before Submitting
    • Check the Code
  • After Submitting
    • Post for Review
    • Reviews and Requested Changes
    • Merge

What is a Pull Request

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.

What makes a good Pull Request

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.

Creating a New Pull Request

Opening a PR

There are two ways to open a new Pull Request:

Through the Github UI

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

Through URL Params

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.

The Details

Confirm Branches

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.

Adding the Title and Description

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.

Title

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.

Description

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.

Before Submitting

Check the Code

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.

After Submitting

Post for Review

To get things moving, we have a couple logistical things we have to do.

• Add ready for dev lead label to the PR
• Move the associated issue to the Ready for Review section in our project board
• Post in the #expunge-assist-dev channel with a link to your newly created PR.

Reviews and Requested Changes

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.

Merge

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!