GitHub Pull Requests and Code Review Explained for Beginners

Every professional software team on the planet shares code. Not by emailing zip files or copying folders — they use a structured process where every single change gets proposed, discussed, and approved before it touches the production codebase. GitHub Pull Requests are the mechanism that makes this possible, and they're the beating heart of collaborative software development at companies like Google, Netflix, and Spotify.

Without a review process, one developer's typo can break the app for every user at 2am on a Friday. One misunderstood requirement can send a team down the wrong path for a week. Pull Requests solve this by creating a formal checkpoint: before any code merges into the main branch, at least one other human looks at it. That human catches bugs, asks clarifying questions, and ensures the change actually fits the bigger picture.

The merge strategy you choose — merge commit, squash, or rebase — directly affects how debuggable your history is six months later when you're chasing a regression at 3am. Branch protection rules are what enforce the review process; without them, anyone can push directly to main.

By the end of this article you'll know exactly what a Pull Request is, how to open one from scratch on GitHub, how to leave a code review that your teammates will actually appreciate, and how to avoid the three mistakes that make junior developers cringe in retrospect. You'll also have real terminal commands you can run right now, today.

What Is a Branch and Why You Need One Before a Pull Request

Before you can open a Pull Request, you need to understand branches — because a PR is really just a request to merge one branch into another.

Think of the main branch (often called main or master) as the official published version of your project — the printed textbook. A branch is your personal draft copy where you can experiment, write new features, or fix bugs without touching the published version. Once your work is ready and reviewed, you merge your branch back into main.

Here's the workflow in plain English: you copy the current state of main into a new branch, make your changes there, push that branch to GitHub, and then open a Pull Request to say 'hey team, I've made these changes on my branch — can someone review them before we include them in main?'

The branch name should describe the work you're doing. fix-login-button-alignment is a great branch name. my-branch or test123 will confuse everyone including future you. One branch per feature or bug fix is the golden rule — keep your PRs focused and small.

At production scale, branch naming conventions matter for automation. Teams use prefixes like feature/, fix/, hotfix/, and chore/ so CI/CD pipelines can auto-assign reviewers, auto-label PRs, and trigger different test suites based on branch type. A hotfix/ branch might skip integration tests and deploy directly to staging, while a feature/ branch runs the full suite.

# Make sure you start from an up-to-date main branch
# This avoids merge conflicts caused by working on stale code
git checkout main
git pull origin main

# Create a new branch with a descriptive name that explains the work
# 'checkout -b' creates the branch AND switches to it in one step
git checkout -b feature/add-user-profile-page

# Confirm you are now on the new branch — the asterisk (*) marks the active branch
git branch

# --- Make your changes to the code here ---
# For this example, we'll create a new file to simulate real work
echo "<h1>User Profile Page</h1>" > user-profile.html

# Stage the new file — 'add' tells Git to track this file in the next commit
git add user-profile.html

# Commit with a message that explains WHAT changed and WHY
# Present tense, imperative mood is the professional standard: 'Add' not 'Added'
git commit -m "Add initial user profile page HTML structure"

# Push this branch up to GitHub so others can see it
# '-u origin' links your local branch to the remote GitHub branch (only needed first time)
git push -u origin feature/add-user-profile-page

How to Open a Pull Request on GitHub Step by Step

Once your branch is pushed to GitHub, opening the Pull Request takes about two minutes — but writing a good PR description takes a bit more thought, and that effort pays off every single time.

After you push a branch, GitHub usually shows a yellow banner on the repository page saying 'Your recently pushed branch... Compare & pull request'. Click that button. If the banner is gone, click the 'Pull requests' tab, then 'New pull request', and select your branch from the dropdown.

The PR form has three key parts: the title, the description, and the reviewers. The title should be a one-line summary of what the change does. The description is where you explain the context — why does this change exist? What does it do? How can the reviewer test it? A template like 'What, Why, How to Test' makes this systematic.

Assigning reviewers is critical. GitHub lets you request specific people to review your code. In a team setting, at least one approval is typically required before merging. You can also add labels ('bug', 'enhancement'), link to a related issue, and mark a PR as a 'Draft' if it's not ready for review yet — that's a great way to share work-in-progress and get early feedback without it accidentally getting merged.

At senior levels, the PR description is also where you document your design decisions. If you chose Event Sourcing over CRUD, explain why. If you skipped a test type, explain why. Future developers (including future you) will read the PR description when investigating why a piece of code exists. A PR with no description is a black box six months later.

## What Does This PR Do?
<!-- One or two sentences. What is the end result of merging this branch? -->
Adds an initial HTML structure for the User Profile page, which will display
the logged-in user's name, avatar, and recent activity feed.

## Why Is This Change Needed?
<!-- Link to the issue or explain the business reason -->
Addresses issue #47 — users currently have no dedicated profile page.
This is the first step in the Q3 personalisation milestone.

## How to Test It
<!-- Tell the reviewer exactly what steps to follow to verify the change works -->
1. Pull this branch locally: `git fetch && git checkout feature/add-user-profile-page`
2. Open `user-profile.html` in a browser
3. Confirm the heading 'User Profile Page' renders correctly
4. Confirm no existing pages are broken by checking `index.html` still loads

## Design Decisions (if applicable)
<!-- Document WHY you chose this approach over alternatives -->
- Chose server-side rendering over client-side SPA for this page because
  the profile data is static and SEO is a requirement.
- Used PostgreSQL `jsonb` column for user preferences instead of a separate
  table because the data is read-heavy and rarely queried independently.

## Risk Assessment
<!-- For changes touching critical paths -->
- Risk level: Low — this is a new page with no dependencies on existing flows.
- Rollback plan: revert this PR. No database migrations involved.

## Screenshots (if relevant)
<!-- Drag and drop images here — essential for any UI changes -->
[Before: no profile page exists]
[After: /user-profile.html shows heading]

## Checklist
- [x] I have tested this change locally
- [x] I have added comments to complex code sections
- [ ] I have updated the documentation (not needed for this change)
- [x] No new console errors or warnings introduced

How to Do a Code Review That Actually Helps

Being asked to review code is a responsibility, not a chore. A good review catches real bugs, shares knowledge across the team, and makes the codebase better. A bad review is either rubber-stamping everything or leaving vague, discouraging comments.

On GitHub, click the 'Files changed' tab in a PR to see a side-by-side diff — the red lines are what was removed, the green lines are what was added. You can click the '+' icon that appears when you hover over any line to leave an inline comment on that specific line.

There are three things to look for when reviewing: correctness (does it actually work?), clarity (can I understand what this code does in 30 seconds?), and consistency (does it follow the patterns the rest of the codebase uses?).

When you leave a comment, be specific and constructive. Instead of 'this is wrong', say 'this function will throw a null reference error if the user has no profile photo set — what if we add a fallback here?' GitHub lets you prefix comments with Nitpick: for minor style preferences so the author knows what's critical versus optional.

When you're done reviewing, click 'Review changes' and choose one of three options: Comment (general feedback, no decision), Approve (looks good to merge), or Request Changes (specific issues that must be fixed first). Only approve when you'd genuinely be comfortable with this code shipping.

At the senior level, code review is also about architectural consistency. Does this new service follow the same error handling pattern as the rest of the codebase? Does it use the same logging format? Does it introduce a new dependency that the team needs to evaluate? These are the questions that separate a senior review from a junior review.

// This is the kind of code you might review in a PR
// The inline comments below simulate what a good reviewer would flag

// REVIEWER COMMENT on line 3:
// 'getUserData' is too vague. What kind of data? Rename to 'fetchUserProfileById'
// to make the intent clear without reading the implementation.
function getUserData(id) {

  // REVIEWER COMMENT on line 7:
  // No input validation here. What happens if 'id' is null, undefined,
  // or a negative number? This will hit the API and potentially return
  // confusing errors. Suggest adding: if (!id || id <= 0) return null;
  const apiUrl = `https://api.example.com/users/${id}`;

  return fetch(apiUrl)
    .then(function(serverResponse) {
      // REVIEWER COMMENT on line 14:
      // We should check serverResponse.ok before calling .json()
      // If the API returns a 404 or 500, .json() will still run
      // and we'll get a misleading error, not a clear 'user not found'.
      return serverResponse.json();
    })
    .then(function(userData) {
      return userData;
    })
    // REVIEWER APPROVE NOTE:
    // Good job adding a .catch() — error handling is often forgotten.
    // Consider logging the error to your monitoring service here too.
    .catch(function(networkError) {
      console.error('Failed to fetch user profile:', networkError);
      return null;
    });
}

// IMPROVED VERSION after review feedback:
function fetchUserProfileById(userId) {
  // Guard clause — fail fast with a clear reason
  if (!userId || userId <= 0) {
    console.warn('fetchUserProfileById called with invalid userId:', userId);
    return Promise.resolve(null);
  }

  const profileApiUrl = `https://api.example.com/users/${userId}`;

  return fetch(profileApiUrl)
    .then(function(serverResponse) {
      // Explicitly check for HTTP errors before parsing the body
      if (!serverResponse.ok) {
        throw new Error(`User profile API returned status: ${serverResponse.status}`);
      }
      return serverResponse.json();
    })
    .then(function(userProfileData) {
      return userProfileData;
    })
    .catch(function(networkError) {
      console.error('Failed to fetch user profile:', networkError.message);
      return null;
    });
}

Merging a Pull Request and Keeping History Clean

Once a PR has the required approvals and all CI checks pass (tests, linting, etc.), it's ready to merge. GitHub gives you three merge strategies and picking the right one matters for keeping your Git history readable.

'Create a merge commit' preserves every commit from your branch and adds a merge commit on top. This is great for long-running features where you want to see the full development history.

'Squash and merge' takes all your commits and compresses them into a single commit on main. This is perfect for small features or bug fixes where your branch had messy 'WIP' or 'fix typo' commits that aren't worth preserving. The result is a clean, linear history.

'Rebase and merge' replays your branch commits directly on top of main without a merge commit, keeping history linear. It's the cleanest option but can cause confusion if your branch had public commits others were building on.

After merging, always delete the feature branch — GitHub shows a 'Delete branch' button right after the merge. Stale branches pile up fast and confuse the whole team. Locally, run git branch -d to clean up too.

If the PR has merge conflicts — meaning main changed in ways that clash with your branch — you'll need to resolve them before merging. GitHub can handle simple conflicts in the browser, but for complex ones, resolve them locally.

At the production level, the merge strategy you choose affects how debuggable your history is. When you're chasing a regression at 3am using git bisect, a clean linear history (from squash or rebase) makes bisect dramatically faster. A branched history with 50 merge commits makes bisect nearly unusable because each merge commit is a diff of diffs.

# --- After your PR is approved and merged on GitHub ---
# Switch back to main and pull the freshly merged changes
git checkout main
git pull origin main

# Confirm your feature branch changes are now part of main
# The --oneline flag shows a compact one-line-per-commit view
git log --oneline -5

# Delete the local feature branch — the work is done, the branch is no longer needed
# '-d' (lowercase) is safe: it refuses to delete if the branch hasn't been merged yet
git branch -d feature/add-user-profile-page

# Confirm the branch is gone from your local machine
git branch

# --- If you need to resolve a merge conflict before merging ---
# First, pull the latest main into your feature branch to surface the conflict locally
git checkout feature/add-user-profile-page
git fetch origin
git merge origin/main

# Git will tell you which files have conflicts, e.g.:
# CONFLICT (content): Merge conflict in user-profile.html
# Open that file — you'll see conflict markers like this:
# <<<<<<< HEAD  (your changes)
# <h1>User Profile</h1>
# =======  (what's in main)
# <h1>User Details</h1>
# >>>>>>> origin/main

# Edit the file to keep the correct version, then:
git add user-profile.html
git commit -m "Resolve merge conflict: keep User Profile heading from feature branch"
git push origin feature/add-user-profile-page
# Now your PR on GitHub can be merged cleanly

# --- Verifying merge strategy on GitHub ---
# Check what merge options are available:
# Go to repo Settings > General > Pull Requests
# Options: Allow merge commits, Allow squash merging, Allow rebase merging
# Enable the ones your team uses, disable the rest to enforce consistency

Frequently Asked Questions