I work at a small company. We’re a couple of developers, with a technical director managing us all and reporting problems.
This is largely a rant. I’m annoyed at poorly reported issues.
tl;dr : a good issue has…
- A clear title
- A clear description
- All the informations (properly formatted) available to the reporter
- Good tags
Formatting, Speaking
- Don’t title your issue in all caps. ON THE INTERNET, USING CAPS IS LIKE SHOUTING. DO YOU SHOUT AT YOUR DEVELOPERS IRL? NO? THEN DON’T DO IT IN AN ISSUE TITLE. KTHX*
- Don’t say hello, nor “hello [name-of-the-person-who-is-supposed-to-manage-the-issue]”. You probably said hello to that person earlier, and it’s just adding additional useless noise to your poorly reported issue. And there is the “assignee” tag.
- Don’t sign neither. It’s not email.
- Code, logs and commands aren’t formattable text. It’s pre-formatted text. HTML has two magical elements: <pre> and <code>. In Markdown it’s `text`(for <code>), and ```…``` (for <pre><code>, aka code blocks). So:
- Don’t fucking paste code, outputs or commands without a <pre><code> block (and some code may even not display poprerly without code blocks, like HTML).
- When speaking about classes, functions…: `wrap them` in a inline <code>. It’s just more readable.
The Issue
Reporting issues is a job. You have to think. If it takes you less than 5~10 minutes: you are probably doing it wrong.
When I encounters a badly reported issue, I don’t even want to really understand it. It annoys me. I don’t want to help you if you don’t want to make some effort to help me help you.
Choose a GOOD title
Some things don’t belong in a title:
- Don’t add useless things like [EMERGENCY], [ULTRA-MEGA-HYPER-URGENT], [KITTENS ARE DYING], “Question”, “Asking for advice”. A lot of issue trackers have a tag system : use it, it’s why the tracker exist!
- Describe the issue, not the context
- Choose a clear, detailed (while keeping it simple) title. For example, don’t say “Impossible to create User”, but “Failed to create User: HTTP error 422"
Choose the Right Project
Let’s say you have an application in two parts: backend and frontend. Part of your job is to pre-figure out where the issues stands. You have an HTTP error in the frontend? It’s probably a backend issue. Report issue to the backend with the full request you browser made.
Setting the context
Every issue has a context, and developers aren’t magical creatures than can create a psychic link with stuff running on your own computer to get intel.
Always, always, always, always, give all the information you have:
- If you executed code, your code (entire code, not just a part of it)
- Which commands you executed
- the logs. No, seriously. THE LOGS. ALL OF THEM. Don’t cut parts of it unless you are 100000% sure it’s useless information. And even if you are sure, give it anyway.
In this case, more is better than less.
Issues In Production
Sometimes you have an issue in production. There are two types of production issues:
- Operational. Badly configured deployement, …
- Software.
Theses two kinds of issues are very different. You probably don’t want to report an operational bug in your software project. Your job here is to try to reproduce the bug on another deployment (staging instance, …).
If you can reproduce, it’s probably a software issue. If not, it’s probably an operational one.
And give all the information you have, again. The project may have tracing tools, an administration interface with logs. If your developer created theses tools, it’s probably because he was excepting you to use them.
theses rules appy to comments, too
Do you have a new update about an issue ? Then give all the new information. Even if it didn’t change!
*: Unless it’s the international caps lock day !
