How to Create a GitHub Pull Request and Get Code Reviews: A Beginner's Guide

Submitting your first Pull Request (PR) can be nerve-wracking because someone will actually judge your code. However, once you get the hang of it, PRs become a powerful tool for learning and improvement. Today, let's walk through how to craft a PR by making small changes, explaining them clearly, and getting useful feedback.

What is a PR and Why Do You Need It?

A Pull Request is a method of submitting your changes to a project's main branch and getting feedback from team members or open-source maintainers.

• Share Your Changes: Document what you changed and why.
• Validation: Other eyes help catch bugs and edge cases.
• Knowledge Sharing: Review comments themselves become educational.

Practice Scenario: Creating a PR by Modifying Documentation

Start small by updating a document like the README.md. For instance, let’s add a line explaining usage and open a PR.

Step 1: Fork, Clone, and Create a Branch

In your terminal, run:

git clone repository-url
cd repository-folder
git checkout -b docs/add-usage

A clear branch name reflects its purpose. Prefixes like docs/, fix/, or feat/ depend on team conventions.

Step 2: Make Your Changes and Commit

Add a line to README.md, then check the status:

git status
git add README.md
git commit -m "docs: add usage line to README"

Commit messages should be concise yet specific. Avoid vague terms like "update."

Step 3: Push and Create the PR

git push -u origin docs/add-usage

Go to GitHub and click "Compare & pull request" to create a PR.

Tips for Writing Effective PRs

A PR description is not a novel; it’s a guide for reviewers. Use a template like this:

PR Template Example

Title: docs: Add one line usage example to README

Body

• Summary: Added a single line to demonstrate usage in the README.
• Reason: Users found it challenging to understand the initial setup.
• Testing: Checked rendering and formatting.
• Screenshots: (Optional)
• Related Issue: (If available) #IssueNumber Focus on the "why" and "how it was tested." This speeds up the review process.

Keep Your PRs Small and Focused

Common errors include:

• Unnecessary formatting changes in a documentation update.
• Combining feature additions with refactoring. Larger PRs slow down the review and dilute feedback. Stick to one purpose per PR.

Requesting Code Reviews Effectively

Instead of saying, "Please check," specify what you need feedback on:

• "Could you verify if the error handling is appropriate here?"
• "Is there a better name for this function?"
• "I’m unsure if this part has performance issues. Can you check?" If urgent, note the review priorities in the PR body. Example: "Key changes in parser.py's parse() function, others are test codes."

Common Review Challenges for Beginners

When Feedback Feels Personal

Reviews improve code, not evaluate you. If uncertain, ask: “Is there a better way to approach this? What cases might I have missed?”

How to Address Review Comments

After incorporating feedback, commit to the same branch, which automatically updates the PR.

git add .
git commit -m "fix: address review comments"
git push

Clearly Communicate Resolutions

After making changes, update GitHub threads briefly: "Updated using ~. Tests passed.", and mark as resolved.

Last Checklist Before Merging

Ensure the PR title represents the changes.

The “why” is clear in the description.

Testing and validation details are included.

No unnecessary file changes.

You’ve responded to all review comments.

Remember, a PR isn’t about perfection but about improving through reviews. Though we started with a document tweak, you can apply this process to feature additions too. Try making a test-inclusive PR next for faster growth.