Over the last few months, the Vox Product team has made some big moves with Chorus, our platform for digital publishers. We’ve opened up Chorus to partners and this new approach pressed us to rethink our team structure. Now, three formerly separate groups within our product team (publishing, video, and audience) work under the Chorus umbrella.

With engineers coming together from different teams, structures, work styles, and GitHub repositories, it was time for us to step back and establish how we collaborate as a newly unified team. One area we focused on is pull requests (PRs), with a specific focus on the template we use for writing PR descriptions.

Challenges of the current pull request template

Context

Pull requests provide context for other coworkers during code review by outlining the high-level reason for a certain change and why a particular approach has been taken. Until recently, each repository in our GitHub organization had a different pull request template or no template at all, meaning that the amount of context or explanation for code changes varied depending on the team, app, engineer, and PR. This was not ideal.

The main Chorus app had a PR template, but it wasn’t updated regularly and wasn’t specific to any team or workflow, so in many scenarios, parts (or all) of it were irrelevant. As a result, the template was used with varying levels of adoption depending on the team, type of code change, or urgency of work.

Most people deleted the portions of the template that weren’t applicable, while others deleted the PR template entirely—usually for emergency fixes or seemingly straightforward changes that, according to the engineer, didn’t need the overhead of a long PR description.

As our teams came together, we started to review pull requests across different codebases more frequently. We found that the descriptions sometimes lacked context to the change being made or the issue it solved, making it difficult for engineers who weren’t as familiar with the codebase to provide sufficient code review.

Adding to the confusion, we recently adopted Jira as our issue-tracking software. This resulted in different groups describing their work in different ways in different places; in some cases, important information existed only in the Jira issue, or the Jira issue description didn’t paint the full picture surrounding the work. Again: not ideal.

Archival

PR descriptions typically include links. However, links can go stale as we retire or adopt new tools or bug trackers over the years. Without including the context or content of our links, it forces us (and our coworkers) to spelunk for the source of a code change through Slack or people’s brains. Good PR descriptions also document institutional knowledge, which ensures we don’t have single points of failure in understanding how the codebase has changed over time.

Communication

Pull requests are not solely used or reviewed by engineers. We owe it to our colleagues to clarify the work we’re doing and make the context in which we work accessible to others. A clear description allows our fellow team members—including designers, product and project managers, community managers, and product writers—to review the work, keep track of changes and decisions, and communicate with our users.

How we iterated on our pull request template

Objectives

To blaze a path forward for pull requests, two of our engineering managers convened a task force made up of members from across the Chorus team: engineers, a designer, and a product writer. We wanted to establish baseline expectations for our PR descriptions that allow them to serve as an accessible artifact for anyone who reads them.

It’s important for us to establish baseline expectations for our PR descriptions so that they serve as an accessible documentation artifact for the Chorus team. Clear PR descriptions will help us better understand what our engineering team members are working on, allowing for quicker and more reliable code reviews, and will also allow us to revisit changes more easily in the future.
— PR task force documentation

Our main objectives were to:

1. Audit and refine the PR description templates

We aimed to formalize a set of documentation areas and establish PR description guidelines for the Chorus engineering team across three different types of work: features, bug fixes, and emergency updates. However, every PR should provide enough background information to contextualize the changes for stakeholders in the product, design, and community teams with whom we work with closely.

2. Create a baseline for how we document technical changes

To ensure a basic and consistent level of documentation in the specified areas, our secondary goal was to create one comprehensive PR template to be used across all Chorus repositories (GitHub provides the ability for repositories to store one PR template).

Considerations

Over the course of a few weeks, the task force met for divergent and convergent discussions around the following questions:

• How might we best document product changes?
• How might we make the background and context of these changes more accessible?
• How might we ensure we’re documenting with an eye toward current coworkers reviewing PRs?
• How might we ensure we’re documenting with an eye toward future coworkers reading through old PRs for the source of a change?
• How might we best document changes for coworkers who are not engineers?
• How might we establish best practices that are flexible enough for the wide range of work the Chorus team is responsible for?

Outcome

After several conversations, we outlined a proposal for a new pull request template. We shared it with engineering leadership first, and then the broader engineering team. Finally, we applied the new template to all Chorus repositories.

Final PR request template for Chorus

Purpose

This area should provide an overview of why the work is happening and, within reason, should include relevant links to the ticket, product/design briefs, and engineering plans. We shouldn’t assume familiarity with the history of this work.

• “What is the context of this pull request? Why is it being done?”

Changes

This area should provide an overview of the code changes, especially pointing out key files and significant areas of change. It should call out and summarize any tricky or complex logic as well as include illustrative screenshots for context if applicable.

• “Are there any changes that need to be called out as significant or particularly tricky?”
• “Are these changes:
  [ ] audience-facing?
  [ ] editorial-facing?
  [ ] engineering-facing?”
• “Include illustrative screenshots for context if applicable.”

Tests

This area should serve as a reminder to be thoughtful about test-coverage.

• “Is this covered by existing tests? New ones? If no, why not?”

Launch plan

This area should provide an overview on the launch plan, covering risks and detailing the deployment plan as well as any necessary migrations. It should note any additional phases of work and link to relevant PRs if applicable.

• “Is this part of a multi-phase project? If so, link to any relevant pull requests.”
• “Are there any user-facing changes? Is downtime expected? If yes, could you notify the Community team via @community in GitHub?”
• “Are there any special considerations for how the deploy and database migrations should be handled?”

Optional GIF

Self-explanatory.

---

Thanks to Shirmung Bielefeld and David Zhou for the PR task force documentation that is referenced throughout this post, and to Gregg Bernstein and Nicole Fenton for their thoughtful edits.