Introducing Improved Pull Request Descriptions for Faster Code Reviews

At Archie AI, we’re committed to making code reviews more efficient and effective. Today, we’re excited to introduce an update to our automated PR description feature that aligns with best practices followed at Google and other leading tech firms.

What’s Changing

Previously, the automated PR description simply listed out the files changed without additional context. While this was helpful, it didn’t fully align with recommended practices for writing effective PR summaries.

With this update, PR descriptions will now concisely cover:

1. What: A one-liner summarizing the changes in fewer than 100 characters.
2. Why: A brief explanation of the purpose behind the changes. This section should clearly convey the problem being solved or the need addressed by the update.
3. How: A detailed list of critical changes, explaining what was modified, added, or removed. This section breaks down the updates by files and provides a concise description of each change.

This format of explaining the what, why and how mirrors highly effective PR summary practices used at leading companies like Google. The PR review summary, which provides guidance to reviewers on what to focus on, remains unchanged.

Example of a New PR Description

Here’s how a typical PR description will look with the new format:

The new format of PR descriptions provides a clear, concise overview of the changes, purpose, and critical updates.

Benefits

This new format is designed to help reviewers quickly understand the scope and intent of the changes, making reviews faster and more effective. Customers have reported that this structured approach makes the PR descriptions more actionable and easier to digest, leading to quicker approvals and a more streamlined review process.

“I love how the new format concisely explains the motivation behind the changes right up front. It helps reviewers understand the full context and leads to more thoughtful discussions.” — Engineering Manager of a fintech startup using Archie AI

Final Notes

While the PR description format has been enhanced, the PR Review Summary remains unchanged. This summary continues to serve as an input directed at the reviewer, focusing on what specific aspects to look at during the review.

We believe this update will significantly improve the quality of PR descriptions and help teams maintain consistency and clarity across their code reviews. As always, we appreciate your feedback and look forward to hearing how this new feature is making a difference in your workflow.

Try it out at Archie AI.