How to Write the Perfect Pull Request Description

How to Write the Perfect Pull Request Description

Why does it matter?

A key component to building software with a team is the pull request (PR). The holy grail of shipping code to production. A well-crafted PR description can save time, reduce misunderstandings, and lead to more robust and maintainable code. It's your first line of sight of what has changed.

What is the Goal of the PR Description?

The primary goal of a PR description is to communicate the intent and context of the changes introduced. This includes detailing what was done, why it was done, and how it was accomplished. The PR description aids reviewers in understanding changes, identifying potential issues, and ultimately approving the merge.

Another function is to document the changes for future reference. When things go wrong or when the code needs to be revisited months or even years later, a well-documented PR can be a huge resource.

Finally, the PR description should help other developers quickly identify what has been affected. For example, if a change to a sensitive file has occurred, you can find out the severity of the situation and whether or not to react.

What Are Engineers and Developers Looking For?

Developers reviewing a PR typically look for several key pieces of information:

  • Context: Why were these changes made? What problem or feature does this PR address?
  • Scope: What exactly has changed? Which files and lines of code were modified?
  • Implementation Details: How were the changes implemented? Were there any notable design decisions or trade-offs?
  • Impact: What is the expected impact of these changes on the codebase? Are there any potential side effects or areas of concern?
  • Testing: How were the changes tested? Are there any automated tests included? Were there any edge cases considered?
  • Additional Details: Are there external artifacts that will help me understand the changes? Tickets, or feature requests on Jira, Linear, etc.?

What Should I Include in My Description?

A well-crafted PR description should include the following sections:

Overall Summary

A brief overview of the changes introduced by the PR. This should provide enough context to understand the purpose of the PR quickly.

Motivation and Context

Explain why these changes were necessary. Describe the problem that the PR addresses or the feature it introduces. 

Implementation Details

Discuss how the changes were implemented. Highlight any significant design decisions, patterns, or best practices. Mention any alternative approaches that were considered and why they were not chosen. Include libraries or frameworks that have been implemented to achieve this change.

File Changes

Detail the specific changes made. This can include:

  • A list of modified files
  • Descriptions of major changes in each file
  • New functions or classes added
  • Changes to existing functionality
  • Removed files or folders

Bonus Points: Testing

Explain how the changes were tested. This can include information on:

  • Unit tests
  • Integration tests Manual testing
  • Edge cases considered
  • Any test data used
  • Any test data omitted

Checklist

Checklists are the lifeblood of any engineer.  It can be used as a demonstration of what has been completed already. This can include:

  • Dependencies checked
  • Documentation updated
  • Tests run
  • Code reviewed

This will all depend on your intentional processes. Many larger companies have more specific requirements for the sake of maintaining some form of compliance. This checklist can be an essential form of audit in the case of debugging a problem in production.

How Do I Create a Template on GitHub?

GitHub allows you to create your own template with markdown and include it directly in your repository. This allows your team to automatically inject this template structure in newly opened PRs.

Creating a PR template on GitHub is straightforward and improves consistency across your team. Here’s how:

  1. Create a .github directory in the root of your repository if it doesn’t already exist.
  2. Add a PULL_REQUEST_TEMPLATE.md file to this directory.
  3. Populate the template file with the sections and prompts you want to include.

Here is a super simple example:

### Overall Summary

<!-- Brief overview of the changes -->
<!-- What was the motivation for these changes? -->
<!-- What was implemented in this pull request? -->
<!-- How does this impact the code base if we merge? -->

### File Changes

<!-- List of changes made -->
<!-- List of files added or removed -->
<!-- List of sensitive files changed -->

### Testing

<!-- How were the changes tested? -->
<!-- What tests do we need to add? -->

### Additional Details

<!-- Links to external resources like Jira, Linear or Figma etc -->

### Checklist

- [ ] Code reviewed
- [ ] Tests run
- [ ] Documentation updated
- [ ] Dependencies checked

Can Squire AI help me do this?

Absolutely. Squire for GitHub will automatically generate a description for each new PR opened. Hands free, description auto-pilot. If you leave the description blank, we will automatically analyze each line of code and produce a summary of all the changes.

You can also use our summary variables in your GitHub template to include our analysis as part of your existing template. Here's an example:

### Overall Summary

{{/squire summary}}

### File Changes

{{/squire changes}}

### Testing

<!-- How were the changes tested? -->
<!-- What tests do we need to add? →
				
### Additional Details

<!-- Links to external resources like Jira, Linear or Figma etc →

### Checklist

- [ ] Code reviewed
- [ ] Tests run
- [ ] Documentation updated
- [ ] Dependencies checked

By using the template variables {{/squire summary}} and {{/squire changes}} directly in your description, Squire will generate the summaries for you.

Don't waste any more time writing summaries of your code changes. Install Squire AI today to bring your development process into the 21st century.