GitHub Pull Requests and Code Reviews

1. The Pull Request: A Conversation About Code

At its core, a Pull Request (PR) is more than just a request to merge code. It's a dedicated forum for proposing changes, discussing the implementation, and ensuring new code meets the team's standards before it's integrated.

In the last lesson, we created a PR from a fork. Today, we'll also consider the "shared repository" model, where all team members have access to a single repository and create branches directly within it. The process of creating a PR is nearly identical in both scenarios.

Key Terminology

As you saw in the video, a PR involves merging one branch into another. GitHub uses specific terms for these:

• Base Branch: The branch you want to merge your changes into. This is typically the main or develop branch.
• Head Branch (or Compare Branch): The branch that contains the changes you have made (e.g., your-feature-branch).

The request is to "pull" the changes from the head branch into the base branch.

2. Performing a Code Review: The Other Side of the PR

Creating a PR is only half the story. Once a PR is open, the code review process begins. The goal of a code review is not to criticize the author, but to work together to improve the quality of the codebase. It's a chance to catch bugs, improve readability, share knowledge, and ensure consistency.

When you review a PR on GitHub, you can comment on the PR as a whole or on specific lines of code. However, a common mistake beginners make is to post each comment individually, which can send a flurry of notifications to the author. The professional approach is to batch your comments into a single, comprehensive review.

As the video demonstrated, when you finish your review, you submit it with one of three statuses:

• Comment: You provide general feedback without giving a formal approval or rejection. This is useful for asking questions.
• Approve: You signal that the changes look good and are ready to be merged.
• Request Changes: You indicate that the author must address specific issues before the PR can be merged. This effectively blocks the PR from being merged until the reviewer is satisfied.

3. Code Review Best Practices

The mechanics of a review are simple, but conducting a good review is a skill. It's as much about communication and collaboration as it is about technical correctness.

A few key takeaways from that reading:

• Review the code, not the person.
• Keep PRs small. Smaller changes are easier and faster to review.
• Automate what you can. Use linters and automated checks for style issues, so human reviewers can focus on logic and design.
• Be clear and constructive. Explain why a change is needed.

4. Practical Exercise: The Full PR and Review Cycle

Now, let's put everything together by simulating the entire workflow. Since you're working solo, you will act as both the author and the reviewer of a pull request on your own repository. This is a great way to understand the complete lifecycle.

Goal: Create a PR to add a README.md file, review it, request changes, address the feedback, and finally approve and merge it.

Step 1: Setup Your Project

1. Go to GitHub and create a new, empty public repository. Name it pr-practice. Do not initialize it with a README file.
2. Clone this repository to your local machine:

   git clone git@github.com:YOUR-USERNAME/pr-practice.git
   cd pr-practice
   

Step 2: Author Role - Create the PR

1. Since this is a new project, we'll establish a main branch. First, create an initial empty commit:

   # This creates the main branch without any files initially
   git commit --allow-empty -m "Initial commit"
   git push origin main
   

2. Create a feature branch for your new README.md file:

   git checkout -b feature/add-readme
   

3. Create a README.md file and add some initial text:

   echo "# PR Practice Project" > README.md
   

4. Stage and commit your change:

   git add README.md
   git commit -m "feat: Add initial README file"
   

5. Push your branch to GitHub:

   git push origin feature/add-readme
   

6. Now, go to your pr-practice repository on GitHub. You should see a banner prompting you to "Compare & pull request". Click it.
7. Ensure the base branch is main and the compare branch is feature/add-readme. Give it a title like "Add README file" and click "Create pull request".

Step 3: Reviewer Role - Request Changes

1. On the pull request page, click the "Files changed" tab.
2. Hover over the line with your new text and click the blue + icon that appears.
3. In the comment box, click "Start a review".
4. Write a comment suggesting an improvement, for example: Could we add a short description of what this project is for?
5. Click the "Finish your review" button at the top right.
6. Select "Request changes" and submit the review. You'll see the PR status change to "Changes requested".

Step 4: Author Role - Address Feedback

1. Back in your local terminal (you should still be on the feature/add-readme branch), update the README.md file to address the review comment:

   echo "This project is for practicing the GitHub pull request and code review workflow." >> README.md
   

2. Stage and commit your update:

   git add README.md
   git commit -m "docs: Add project description based on review feedback"
   

3. Push the new commit to the same branch. This automatically updates the PR.

   git push origin feature/add-readme
   

Step 5: Reviewer Role - Approve and Merge

1. Go back to the pull request on GitHub. You'll see the new commit has been added.
2. Go to the "Files changed" tab again and see the new line. It looks good!
3. Go back to the "Conversation" tab. You can now formally approve the changes. Click "Review changes", select "Approve", and submit your review.
4. The PR is now approved. Click the green "Merge pull request" button, and then "Confirm merge".
5. Finally, delete the now-unneeded feature branch by clicking the "Delete branch" button.

Congratulations! You've successfully navigated the entire PR and review lifecycle.

Conclusion

Today you've explored the collaborative core of GitHub. You learned that a pull request is a platform for discussion and that code review is a constructive, team-oriented process for improving quality.

Key Takeaways:

• A Pull Request (PR) is a formal proposal to merge code from one branch (the head) into another (the base).
• Code Review is a critical practice for catching bugs, sharing knowledge, and maintaining standards.
• The professional way to review on GitHub is to batch comments into a single review and submit it with a clear status: Approve, Request Changes, or Comment.
• The PR lifecycle involves creation, review, discussion, updates (pushing new commits), final approval, and merging.

In our next lesson, we'll answer the question: "How do we decide what work needs to be done in the first place?" We will learn how to use GitHub Issues to track bugs and feature requests, effectively turning ideas and problems into actionable work items for your team.