Open Source Software Primer: Issue Etiquette
- How-To Guide
Introduction
This guide covers how you can handle poorly created issues as well as giving an overview of issue etiquette and finishing with a glossary of common software dev terms to help you on your way. But first we need to ask, what do you do when the issue is bad/wrong?
All users are fallible and we all make mistakes. Sometimes an issue is made that is not reasonable. Maybe it can't be fixed, or maybe it's a misunderstanding of how the software works. More often, insufficient information is provided to diagnose the problem, or the information provided does not replicate the problem reported. Perhaps the OP (original poster) doesn't actually understand the piece of code they're talking about. Perhaps you don't!
Every developer reading this knows exactly what I mean because variations on these scenarios play out every day in commercial development. So what do you do about it? How do you handle this kind of problem?
To answer this question, we first need to look at issue etiquette.
Ticket/Issue etiquette
Tickets/issues exist for one key purpose: tracking how the code has changed/is going to change and why. All issues must address this. This is for two reasons: accountability and accreditability.
Accountability & Accreditability
These two concepts underpin version control. They allow people to look back over a whole project and see who did what, who approved it, and who requested it in the first place. Why you would need this isn't immediately obvious but you absolutely do. For example, we need to know who asks for what because this information will affect how issues are prioritised. Or, maybe some very bad code makes it into the release. You would need to talk to whoever wrote and approved it to find out why this had happened. Maybe it was a mistake but maybe they know something we don't and removing it would actually break something else. It is only by tracking requests and fixes that we can get this information.
1 problem = 1 issue
There is one golden rule that should be followed at all times (but disappointingly, rarely is). Which is that 1 issue should only contain 1 problem and vice versa.
An issue should address one thing and one thing only. If there's a discussion on the issue and the scope broadens to include another fix. That means you make a new issue.
- Ticket unveils a new suite of issues?
- Make new issues for each one
- You fix an issue and the OP requests an additional change
- Close that one and make a new issue
- You spot a small error in the code whilst fixing an issue and want to fix it whilst you're there.
- Believe it or not, new issue and fix it there.
- Someone hijacks an issue discussion to mention an unrelated problem
- New issue
- You have to implement some other thing in order to fix an issue
- New issue, even if you probably will need to close it immediately.
One relevant exception is if your issue has multiple steps to be completed. You don't need issues for each step; it is ok to make a checklist in the issue and tick them off as you go. Depending on your chosen poison (GitHub/JIRA/ADO/other) you may be able to spin those checklist items off into sub-issues as well.
"Oh no I have to make a new issue. What do I do??"
Well, making issues isn't super hard, but it is quite dull. This is because it's not enough to just say "I broked it" and leave it there.
Each issue is a record of a problem someone had with the code and this needs to be recorded in as much detail as possible, so that someone else can come along and fix it. The "someone else" might be you, but it also might not, so even if you're planning to fix it yourself you should include enough info for another to come along and do it instead. You don't know what might happen to you before you fix the issue.
If you have a bug, try to provide a "Minimal Reproducible Example" to demonstrate the issue(s) you've found. If no one can replicate what you've reported then the issue is more likely to just be ignored.
If you have a feature suggestion you should share as close to a full specification for what it should do as you can. How should your feature behave in all the potential scenarios it finds itself in? What needs to change to include it? If you need input from other developers you can tag them in the post and start a discussion.
OK but really, what do you do when an issue is "bad"?
Now the basics of issue etiquette are out of the way we can move onto some recommendations for dealing with malformed issues. How do you deal with each scenario?
Insufficient information provided
This includes situations where the bug can not be reproduced. In those cases the information provided is, by definition, insufficient. The OP is not lying. They will have seen this, but they can be wrong about what caused it.
In general, when you encounter an issue with insufficient information:
- Politely ask for the information you need
- If they misunderstand/provide unhelpful information
- Then simply ask again/have a discussion about what you need
- Maybe rephrase/reword your request to help comprehension.
- You can't just message them on Teams! Or email them!
- Also remember this conversation is public, so keep it civil
OP labouring under a misunderstanding
Take this one very carefully because no one likes to be shown to be wrong (especially in public) and you have to make doubly sure you are not wrong as well. You have two options:
- Explain (very) carefully the situation to OP.
- Pass the buck to someone more knowledgeable in the team and get them to handle it.
Issue scope has expanded
If someone has commented a new problem on an existing issue, the best approach is to simply create a new issue for them using the information they provided, tag anyone involved in the new issue and finally leave a comment on the existing discussion explaining what you have done.
Software Development Glossary
In order to help understand how developers talk I've included this glossary of common developer terms with the hope it helps you all understand what is being said a bit better,
"API" - Application Program Interface.
"bork(ed)" - to break, or broken. E.g. "I borked the connection object with this input"
"munge" - to combine two (or more) things into one thing in a crude manner. Except when it doesn't mean this.
"front end" - The user interface. The front-facing bit of the software.
"back end" - The stuff doing all the heavy lifting in the background.
"PEBKAC" - Problem Exists Between Keyboard And Chair
"RTFQ" - Read the *full* question
"Code Smell" - Not something that IS wrong but a pattern of code that has the potential to cause problems.
"LBYL" - Look before you leap
"EAFP" - Easier to ask forgiveness than permission
"LGTM" - Looks good to me
"DRY" - Don't Repeat Yourself
"WET" - Write Everything Twice (DRY's backronym)
"YAGNI" - You aren't gonna need it