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. […]
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
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
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
# 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
Photo by Ricardo Gomez Angel on Unsplash