This isn't going to be an in-depth article or all that technical. But I've been itching to write over the last couple of weeks and this 30-min article is short enough to finish in one sitting right after work. My brain is at that perfect level of fatigue, where the words still come easy, but the thought of reading pages on a topic feels painful 😪

Last week, I made my first PR for my first feature. After weeks of learning, video watching and question asking, I created a new Azure function that logs hello, world to the terminal.

My PR description said as much:

1. Creates Azure function
2. Logs hello, world

Simple. Right?

But then I got PR comments.

The comments themselves weren't the issue, but my logic was. I assumed everyone, being familiar with the "hello, world" approach, would understand this PR was the basis for the Azure function that was to come. Not realizing that even in the shell of a project, decisions have been made-- how to set up the code, what conventions are followed, what triggers make sense etc etc.

So I took a step back, read the comments, stepped away again, re-worded the description, read the comments and then read some PRs and then read the comments again.

Reading the other PRs was the most illuminating. Re-reading the comments at each step helped me piece together what information the reviewer needed. Reading the other PRs showed how different devs approached this.

While short, most of the descriptions were helpful to a new set of eyes. Assuming 0 knowledge of the PR or the associated feature, they offered enough information for the reviewer to proceed.

PR description template

In addition to commit small, frequent PRs, this is the PR template I have so far:

1. This PR will accomplish _____
2. This will in turn have _____ impact on _____
3. Not included in scope for this PR is _____ because of _____

Photo by Karolina Grabowska from Pexels