Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Pull Requests and Reviews

Pull Requests: The Basics

Open your first pull request: choose base and head, write a clear title and description, link issues with keywords, use drafts, push updates and read the Conversation tab.

A pull request (PR) is a proposal to merge one branch into another, with a place to discuss the change before it lands. You push your work to a branch, open a PR, teammates review it, automated checks run, and when everyone is happy the branch is merged. It is the heart of collaboration on GitHub, and writing good ones is a skill worth practicing.

The name is historical: you are asking the maintainer to pull your changes. A PR is not a Git concept, and it lives on GitHub rather than in the repository.

Base and head

Every PR has two ends:

  • The base is the branch you want to change (usually main).
  • The head is the branch that contains your changes (for a fork: your-username:branch-name).

The PR shows the difference between the merge base (where the two lines of history diverged) and the head. Commits that are already in the base do not appear.

gitGraph
  commit id: "A"
  commit id: "B"
  branch feature
  checkout feature
  commit id: "C"
  commit id: "D"
  checkout main
  commit id: "E"

A PR from feature into main contains C and D. E is on main only, so it is not part of the PR.

Opening a pull request

  1. Create a branch and commit.
  2. Push it: git push -u origin feature/dark-mode.
  3. GitHub shows a yellow banner Compare & pull request, or go to Pull requests > New pull request. With the CLI: gh pr create.
  4. Check the base and head, write the title and description, and optionally add reviewers, assignees, labels, a milestone and projects.
  5. Click Create pull request.

A good title and description

The title is a one-line summary in the imperative mood: "Add dark mode toggle to settings". The description answers what changed, why, and how to test it. Many projects supply a template (see the Issues lesson on templates); here is a reasonable structure:

MARKDOWN
## What
Adds a dark mode toggle to the settings page and stores the choice in localStorage.

## Why
Users asked for it in #218, and several reported eye strain at night.

## How to test
1. Run `npm start`.
2. Open Settings and switch the theme.
3. Reload: the choice should persist.

## Notes
The color tokens live in `theme.css`; no existing colors were changed.

Closes #218

Keep a PR small and about one thing. A reviewer can meaningfully read a few hundred changed lines; thousands get skimmed and approved with little attention.

Closing keywords

If the description or a commit message contains close, closes, closed, fix, fixes, fixed, resolve, resolves or resolved followed by an issue reference (#218, or owner/repo#218 for another repository), the issue is closed automatically when the PR merges into the default branch. The sidebar's Development section also lets you link issues manually.

JS Stand-in: find issues a PR will close

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note that Related to #300 is only a link: the keyword is what closes.

Draft pull requests

Choose Create draft pull request (the arrow next to the button) when work is not ready. A draft cannot be merged and does not request reviews from code owners. Mark it Ready for review when it is done. Drafts are a polite way to ask for early feedback or to let continuous integration run while you are still working.

The pull request page

  • Conversation tab: the description, comments, review summaries, commit list, status checks and the merge box.
  • Commits tab: each commit; handy when the commit history tells a story.
  • Checks tab: results of automated workflows (see the Actions chapter).
  • Files changed tab: the diff, where reviewers leave line comments (see Reviewing Pull Requests).

The merge box at the bottom of the Conversation tab summarizes whether the PR can merge: checks passing, reviews required, conflicts with the base.

Updating the pull request

Push more commits to the same branch and the PR updates itself; there is no need to open a new one. If the base moved on and there are merge conflicts, GitHub says so. Resolve them either on the website (Resolve conflicts editor for simple cases) or locally:

Terminal
git fetch origin
git switch feature/dark-mode
git merge origin/main        # or: git rebase origin/main
# fix conflict markers, then
git add . && git commit      # (merge) or: git rebase --continue
git push                     # use --force-with-lease after a rebase

The Update branch button merges the base into your head branch for you.

JS Stand-in: what does the PR contain?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Closing without merging

A PR can be closed without merging, and reopened later. When a branch is merged or closed, the Delete branch button removes it (or enable automatic deletion in the repository settings). Closed PRs remain searchable, so write descriptions you would still understand in a year.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the base of a pull request?

    Base is the target; head is the branch with the changes.
  2. 2. When is an issue closed by writing 'Fixes #12' in a PR description?

    Closing keywords take effect when the PR merges into the default branch.
  3. 3. What is a draft pull request for?

    Drafts cannot be merged until marked ready for review.
  4. 4. You have pushed new commits to the PR branch. What should you do to update the PR?

    A PR tracks its head branch.

Summary

  • A PR proposes merging a head branch into a base branch and hosts the discussion.
  • Write a clear title, a description that explains what, why and how to test, and keep the change small.
  • Closing keywords link and close issues when the PR merges into the default branch.
  • Use drafts for work in progress; push more commits to update; resolve conflicts by merging or rebasing the base.

Next: Reviewing Pull Requests