by Jake Worth on January 5, 2021

Communicating via pull request or issue takes considerable skill. The target audience can range from coworkers, to open-source maintainers you've never met, to yourself in the future. PRs and issues communicate priorities, start conversations, and shape the codebase. If conveying the best information in the most compelling way is of interest to you, read on.

My coworkers and I have developed some techniques to handle the communication opportunity of a PR or issue. Here are the templates we use, and how we use them.

It's a bit more time consuming to ask each customer of your application to fill out these forms. Why bother?

I believe that in almost every scenario, it's the best option. You'll get better contributions, because people who don't care enough to fill out a simple form will self-select out of the process. That's good! The PR or issue should be important enough that they feel their time is justified.

The first thing you can do is make sure your team has a clear and consistent convention around PR names, whether that be ticket number or special keywords like fix or feature. These details set the stage for your reviewers to have an easy time reading your code.

In the body of the PR, I suggest this format:

### What

### Why

### How

What is the reason for this change? I think anybody on the team– dev, PM, QA tester, executive– should be able to parse this; plain English is preferred to jargon.

Example: "Fixes a bug where the count of unread emails was off by one."

Why is this change important? Why is the code worth reviewing? I love filling out this step, because when I reframe my code change from a user's perspective, I often realize some key detail of the experience I've missed.

Example: "It's important that users know how many emails they need to read."

How was this change accomplished? Try to go beyond a play-by-play of the Git diff; that's already available to everyone reading the code. What's unique about this implementation? To what decisions do you want to draw your team members' attention? What are you proud of, or unsure about?

Example: "Migrates the database with an irreversible migration, and removes all references to the class."

Peruse the open issues on any popular project and you'll find long, circular dialogues between maintainers and issue openers, answering repetitive contextual questions like: how do I reproduce this? What were you expecting, and what happened? What kind of computer setup were you using? The template below answers these questions preemptively, saving everyone time and keystrokes.

# Steps to reproduce

### Expected behavior

Tell us what should happen

### Actual behavior

Tell us what happens instead

### System configuration

**Operating System**:

**Browser**:

The more information you can provide, the better! Have a screenshot? Throw it in there! Does this only happen 'some of the time'? Include that! Do you care about this issue– is it preventing you from getting work done? Or do you think it's unimportant? Did you try to solve it? What worked and what didn't? I think issue openers should feel empowered to share details like this. You might be saving someone a lot of work.

Once your team is feeling good about these templates, commit them to the repository like so:

$ mkdir .github
# create templates...
$ git add .github/issue_template.md
$ git add .github/pull_request_template.md
$ git commit -m "Add PR and issue templates 🤘"

Now, these templates will be automatically populated in the textareas of your GitHub PR's and issues.

Thirsty for more? After opening your PR specifically, go to the PR page and comment on your own code! Remember those unique details, decisions you wanted to draw attention to, points of pride, and points of worry? Review your own code and give everyone a shortcut to the important information.

With a PR or issue that follows these templates, and includes as many screenshots, details, and comments as possible, we make code maintenance easier for everyone.

Photo by Ricardo Gomez Angel on Unsplash