How to write a good Pull Request Description?

Conclusion of seeing 1000s of nicely written PRs (called CLs internally at Google)

A good pull request (PR) description is critical for clearly communicating changes to reviewers and capturing context for future reference. It should concisely summarize:

1. What is being changed
2. Why the changes are being made
3. The key changes included

1. Summarize the Changes in One Line

Start with a one-line summary of the changes, using fewer than 100 characters. This should complete the sentence “If applied, this PR will…”. For example:

- Add retry logic to handle transient failures in image upload
- Refactor user authentication to use new Auth0 service

The one-liner appears in PR lists and emails, so make it informative enough to skim.

2. Explain the Purpose and Context

In a few sentences, explain why these code changes are happening — the purpose, context, and motivation. For example:

• Retry logic is needed because image upload often fails transiently due to network blips. Retrying will make the image upload more reliable.
• Refactoring authentication to the new Auth0 service will allow us to support SSO and is part of the Q2 OKR to improve login.

This is also a good place to add bugs link, design doc etc to provider further context.

3. Highlight Key Changes

Give a bulleted list calling out the key changes, with a brief description for each. For example:

- `ImageUploader.js`: Added retry logic with exponential backoff to handle transient failures
- `LoginPage.js` and `AuthService.js`: Refactored to use Auth0 instead of custom authentication
- Added new `Auth0Config` class to encapsulate Auth0 configuration

The goal is to orient the reviewer and call attention to the major touchpoints. Use code references to point to specific files or directories.

Example

Here’s an example of a helpful PR description:

Add retryImage uploads frequently fail transiently due to network issues, causing a poor user experience. This change adds retry logic with exponential backoff when image uploads fail, to improve reliability.
- `ImageUploader.js`: Added retry logic triggered on upload failures 
- `ImageUploader.test.js`: Added test case for retried upload
- `ImageUploader.js`: Extracted backoff calculation to `calculateBackoff` function to facilitate testing logic to image uploader

With a clear PR description like this, reviewers can quickly grasp what’s changing and why, and have a guide to the changed code. The context also helps future readers understand the intention and reasoning behind the code changes.

— —

At Archie AI, we’re automating the boring and repetitive aspect of PR Review so that you focus on high-order task in review. It automatically generate PR Description that you can edit or directly share with reviews who further get a summary of areas to look at during review.