How to Write Good Pull Request Titles that are Scannable, Searchable, and Reviewable

Date: 2025-08-15 | create | creation-cycle | productivity | pull-request | software-engineer |

DISCLOSURE: If you buy through affiliate links, I may earn a small commission. (disclosures)

Pull requests are a critical part of the dev cycle - it's how you get code approved and pushed to prod.

Doing pull requests poorly leads to slower, less thorough reviews which lead to slower dev cycles and higher incidence rate of failures.

In this post we'll discuss a simple system for writing pull request titles that make PRs more scannable, searchable, and ultimately reviewable.

Why write clear PR titles?

The point of a PR title is to be clear:

  • What is this thing? Tells reviewers what the change is and why they were requested.
  • What's the purpose? Allows reviewers to prioritize based on the change.
  • What work is it attached to? Provides context on the business case so they can give a thorough review with limited back-and-forth trying to understand why the change was made in the first place.

Clear PR titles make it easier for reviewers to understand what the PR is about. This makes it easier to scan titles to see what they're doing, easier to search in the future, and helps reviewers prioritize and provide thorough reviews.

How to write clear PR titles

Different orgs have different standards for PR titles so if your org has a standard you should use that. The most important thing is for PRs to have a standard format so that anyone in the org can quickly get up to speed on what a PR is about so they can understand the change and its implications. If you think something is missing, propose a change so the whole org can move in lock step.

Generally the format I like PR titles to be in is like this:

[WORKSTREAM][TASKID] TYPE: CHANGE

An example might be:

[BLOG][HAM-101] Feature: Provide an example of good PR titles

  • WORKSTREAM (Optional) - The workstream indicates what team / org / slice this change is part of. This is not always necessary but in very large organizations (like Meta) is often useful as a way to indicate the area a change belongs to. For example on the IG Media Infra team we would often preface our commits with [IG] so we could indicate this was a change made to support Instagram (vs FB or What's App or Oculus which also lived in our monorepo). Another common usage is to indicate this is related to an ongoing SEV ([SEV]) or incident ([INCIDENT]) to help reviewers prioritize reviews to unblock critical fixes.
  • TASKID - This is the specific task id that this change is a part of. In general most changes should be tied to a task / work item. This allows reviewers to find the task and understand the business context which helps them provide more thorough reviews. It also makes PRs more searchable if you ever wanted to find PRs related to a ticket in the future.
  • TYPE - This is the kind of change. I usually use Feature for net new functionality, Fix for fixing stuff, and Cleanup for other work that is useful but not really changing logic. I like these because it gives the reviewer a head's up on the kind of change so they can better prioritize.
  • CHANGE - This is a short description of the change. It will never capture all the context a reviewer needs (that's what a PR description is for) but it should summarize the change so reviewers know what it's about.

If you're having trouble summarizing your change in one line with this format, your PR may be too big. This is a good rule of thumb that your PR may be doing too many things and should be split out into atomic commits to get better, faster reviews.

Next

So that's how I like to write my PR titles. I find it makes PRs easier to scan, search, and review.

LMK if you have a PR title scheme you prefer!

If you liked this post you might also like:

Want more like this?

The best way to support my work is to like / comment / share for the algorithm and subscribe for future updates.