Bug Report
If you have followed this newsletter for a while, you would notice I usually recommend software engineers pursue a Jerry Maguire “Help me Help you” approach in their day to day work.
First if you did not watch the movie, it’s highly recommended. Please do :) Here is the “Help me Help you” scene.
In the code review post, I recommended to help the reviewer help you (the author) by making it easy for them to approve the pull request.
Today, we will cover a bug report in a way that will help the engineer help you (the person who submitted the bug report) by making it easy for them to quickly find the root cause and fix the bug.
This is the outline I recommend.
Clear and concise title
Priority: How quickly should we tackle this bug? Usually a range between 1-5.
Severity (optional): What is the impact of this bug? Usually a range between 1-5
Repro Steps: Describe every single step needed to repro the bug.
Expected Result: What was expected to happen? What is the expected behavior?
Actual Result: What is actually happening
More details: Add as much details and context (user, environment, version, platform, time, repro once or every time, repros consistently or not, etc…) as possible. Add any screenshot that will be useful. Finally, attach any logs, network requests/responses and instrumentation that will be useful for the engineer while debugging.
I have seen people record their screen and comment which is really helpful for the engineering team. Loom is great if you want to do this (not an ad)
Software Engineering from the Frontlines on Maven
If you liked this article, I will be teaching a “Software Engineering from the Frontlines” course on Maven where I will teach hard-learned lessons I acquired developing large-scale products at companies such as Uber, Airbnb, and Microsoft.
