There are a multitude of ways contributing to open source. Slinging code, writing documentation, improving on features, research, web design, helping newcomers, keeping the community engaged. However there is one part that is often overlooked, and it is the most fundamental thing that every user can do: report problems and logging a ticket.
A problem not reported is a problem not fixed, and that hurts everyone, the user – they have a problem, the project – they have a problem they don’t know about, the community – someone might run into the problem too.
That said writing tickets isn’t trivial, there is a big difference between ‘a ticket’ and ‘a good ticket’. Writing a good ticket requires skill and consideration but it is worth it.
A good ticket:
- helps and improves the project it is filed with
- makes everyone happy
- gets solved faster
On the other hand a bad ticket:
- is a burden on the project
- everyone is miserable
- will usually linger around longer or might not even get solved at all
I’ve been doing open source work for quite a while, both as maintainer and as user of libraries, programs and projects. I’ve seen and written both good and bad tickets. It took me a long while to realize the difference, and I think only slowly, with maintaining something as big as Project-FiFo I start to get a grasp on what exactly makes a ticket good. I would like to share this, and I will say ahead of time this are my experiences and opinions and people are welcome to agree or disagree. Take something from it or entirely disregard it. What works for me might not work for someone else. I write this mostly from the point of view of a maintainer, not a participant so some of the points will be biased.
Some considerations
Users outnumber maintainers, in result that means that tickets or problems outnumber the people dealing with them. So it worth keeping in mind that wile for the author it is ‘just one ticket’ the recipient usually deals with a lot more, it might be one in ten or one in a hundred. On the flip side, communicating progress is important for the author it is ‘just one ticket’ after all, so weeks of silence can quickly turn into frustration. It doesn’t have to be a resolution but often a simple “sorry it’s read, but it will take a while to get to it” can go a long way.
It is never fun to find out something is wrong. It is a pretty human reaction but not always helpful. This is very two fold, when writing a ticket accusations, anger and frustration are usually counter productive in a ticket. So can be, trying to be clever, there is a great article on that. All those goes is worth thinking about for both users and maintainers. In addition to that, as a maintainer, it is very important (yet very hard) not to take things personal.
Your thoughts are your own, which is good in many senses but it can be a problem when reporting a bug. Writing a ticket keep in mind that whoever reads it does not know what went on on your head when they do so. They don’t know the context, they don’t know your goals, your background, all of the little things that play into it are unknown to them. And I want to play that out by example to really drive this point home.
Here is my bug report: “There is a double space”. This is perfectly clear to me, I’ve just seen it. The report makes sense with all the additional information I have. You might conclude I’m probably talking about the article, now you might go and guess it’s the previous paragraph I’m talking about, might go debugging trying to search for it. All that just because I failed to mention the details that were obvious for me. So lets try again: “There is a double space in the second paragraph of this section, third sentence between ‘very’ and ‘two'”. Small difference but bug impact, the first version takes considerable time and cognitive effort to solve, the second is trivial.
Show that you care, when submitting a ticket to a open source project you are literally asking someone to do free work for you. It helps to show that you are willing to put effort into the ticket yourself and value the time of your counterpart. This means adding details, doing some research on your own and show the ticket you write some love.
A recipe for good tickets
Take this with a grain of salt, think for yourself but if you are unsure I found that the following steps usually yield very good results. So I’ll propose a template, some of the sections will not apply in every case, and it might miss others.
Hi, I have been trying to <goal>. For that I’ve done <action>, and seen <result> but I was expecting <expectation> to happen.
I’ve not found anything about this in the documentation. (Or I have found <documentation> in the docs but it didn’t resolved my problem).
I am using <additional components> and the version <version>. It is also worth mentioning that <anomalies>.
Attached the logs from around the time of the event, taken from <logs>. You can see the error at <location in logs>.
Also attached are <additional aids and description>
The problem can be re-produced with: <steps>.
goal
Perhaps the most important of them all, what are you trying to do, not what did you do, what is the goal. Details are important this also helps to identify AB-problems (where the goal and the action don’t align) or simple misunderstandings.
action
What was it that was done, again detailed enough that someone who knows nothing about your past hour can understand it.
result
What did happen then? “it did not work” is not a good thing here! How didn’t it work? What made you think didn’t work? Details are still incredibly important.
expectation
Now that you described what you went through it’s good to also know what you were hoping the result to be. Whoever reads the ticket can’t read your mind, so it is important to convey the expectations.
documentation
Have you tried to consult the documentation? It might just be too unclear there, adding any information about what you tried or looked up already will help the recipient to narrow things down. Reading the documentation also shows initiative, which generally proves the reception of a ticket.
additional components
Are you using a specific browser? Are you running a odd terminal emulator? Is your environment very constraint? Is there something special about the network? All those things might be obvious to you but not to the recipient. Of cause there are limits to what is sensible but try to actively think about what additional components and interactions there are that might affect things.
logs & location in logs
If the system in question keeps logs or prints error messages including them usually is a great way to add information. But just vomiting the last 6 month of logs into a ticket is counter productive, point out locations that might be relevant. Add a timeframe of the event but don’t just a few lines what hapend the 5 minutes before and after might still be important. Never ever modify logs to conceal your own errors – yes I’ve seen this more then once and it is infuriating.
additional aids and description
Sometimes additional aids such as console history, copies of the output or screenshots can be helpful to explain the point. But when adding them always include a description and explanation of what it is you want to convey. A screenshot without details on what to look for is entirely worthless, the output from a program without the command ran and what section of the output to look at is too. (remember the double spaces?)
steps
This is the perfect case, if the problem can be reliably reproduced by taking a number of steps it will make solving the ticket a lot lot easier. It will allow the maintainer to gather additional information without the need for a constant forth and back.
Leave a Reply