How to Open a Pull Request on GitHub

A pull request titled Update with an empty description tells reviewers nothing. They have to open every file to work out what changed and why, and many will put the review off until they have time for that. The way a pull request is opened often decides how quickly it gets merged. Reviewers also judge the work by how it's presented: a careless pull request invites a careless review.

Opening one on GitHub takes a minute: after work is saved to a branch, GitHub offers a shortcut, and a form asks for a title, a description, and reviewers. That minute shapes the whole review. A clear title, a short explanation of why the change exists, screenshots of anything visual, and a note on how to check it give reviewers what they need. A draft pull request lets you share work early without asking for approval yet, and templates can prompt for all of this automatically.

Good pull requests are small and explain themselves. When the description answers a reviewer's first questions before they're asked, the review becomes a quick check instead of an investigation. Keeping each one focused on a single change makes that possible, and it makes any later undo cleaner too.

The Compare & pull request banner

After commits are pushed to a branch, GitHub shows a yellow banner above the file list with a Compare & pull request button ^[1]. Selecting it opens the form for a new pull request, with the branches already filled in.

The same form can be reached from the Pull requests tab with New pull request, by choosing the base and compare branches by hand. Either way, the form asks for a title and a description, and lists the commits and changed files underneath.

That list is a last chance to catch surprises. A settings file or an unrelated page in a pull request about one small fix is easier to remove before anyone is asked to review it.

Writing a pull request title

A pull request title appears in lists, notifications, and review requests, usually before anyone opens the pull request. Like a commit message, it works best as a short summary of the result: Add allergy notes to the menu page rather than Menu changes or Update index.html.

Many teams add a little structure, like the area of the product at the start or the related issue number at the end. With squash merging, the title often ends up as the commit message on main, so a clear one keeps the history readable too.

A good test is whether the title still makes sense a month later, to someone who wasn't part of the conversation.

Writing a useful pull request description

A pull request description answers a reviewer's first questions before they're asked: what changed, why, and how to check it. Three short parts usually cover it: a summary of the change, the reason or the linked issue, and steps or a link to see the result.

A description like Updated stuff forces reviewers to rebuild all of that from the diff, which takes longer and misses the intent behind the change. Intent matters, because a reviewer can only judge whether a change is right by knowing what it was meant to do.

Descriptions support Markdown, so headings, task lists, and screenshots all work. Keeping it short is still the goal: a few lines that save a reviewer 10 minutes.

Before-and-after screenshots for visual changes

For changes people can see, a picture beats a paragraph. Dragging or pasting an image into a pull request description uploads it and inserts the Markdown that displays it, so a before-and-after pair takes seconds to add.

Before-and-after pairs let reviewers judge a layout or copy change without running anything, and they turn the pull request into a visual record of how the design changed. A small table with a Before column and an After column keeps the two side by side.

Many hosting services also add a preview link to each pull request: a temporary version of the site with the change applied. Linking it in the description invites reviewers to click through instead of imagining the result.

Pro Tip! Screenshots at the same size and zoom make differences obvious, while mismatched crops hide them.

Pull request templates

A pull request template pre-fills the description of every new pull request with headings and prompts. It's a Markdown file stored in the repository, usually as .github/pull_request_template.md, and it applies once it's merged into the default branch ^[2].

A good template is short: a summary, the related issue, how to test, and a checklist for things that are easy to forget, like screenshots or updated documentation. Teams can keep several templates in a PULL_REQUEST_TEMPLATE folder for different kinds of change.

Templates make descriptions consistent across people and tools, so every pull request arrives with the same structure, whoever or whatever opened it.

Draft pull requests

A draft pull request shares unfinished work without asking for approval. It's created by choosing Create draft pull request from the dropdown next to the create button, and it can't be merged until it's marked ready ^[3].

Drafts are useful for early feedback. A designer can open one as soon as a layout takes shape, and teammates can comment while it develops. Code owners aren't automatically asked to review drafts, which keeps their notifications for finished work.

When the work is done, Ready for review in the merge box turns the draft into a normal pull request and requests reviews from any code owners ^[4]. A pull request can also go back to being a draft at any time.

Requesting reviewers

Reviewers are requested from the Reviewers section of a pull request's sidebar, by picking one of GitHub's suggestions or typing a name ^[5]. Requesting a review needs write access, and the person or team requested needs at least read access to the repository.

Asking specific people beats hoping someone notices. A request notifies the reviewer and puts the pull request on their list of reviews to do. If code owners are set up, the right people are added automatically.

After addressing feedback, re-requesting a review with the icon next to a reviewer's name signals that the pull request is ready for another look.

Keeping pull requests small

Small pull requests get better reviews. Google's engineering guide notes that small changes are reviewed more quickly and more thoroughly, are less likely to introduce bugs, and are simpler to roll back ^[6].

A pull request that fixes a typo, redesigns the header, and updates prices is three changes sharing one title. Splitting it lets each part be reviewed, merged, or undone on its own, and a problem in one doesn't hold up the others.

AI tools tend toward large pull requests, because they change whatever they pass along the way. Asking for one change per pull request is a habit worth bringing to every prompt.