How to create a good first Bug Report

Translate This Post

A software bug is an error or flaw in a program that produces incorrect or unintended results. Developers work hard to produce software that looks and works as intended, but bugs are as inevitable as death and taxes. The Wikimedia Foundation uses the bug tracker Bugzilla as the system for users to report bugs they encounter while using MediaWiki and Wikimedia sites.

Can you make it happen again?

So, you think you’ve run into a bug and want to report it to Wikimedia’s bug tracker. The first thing to do is to try to reproduce the bug with concrete steps. These steps help developers reproduce the bug, which allows them to investigate the source of the issue. If the bug does not appear consistently, you can still file it, and developers will likely ask you questions to gather more information about the bug.

Has it already been reported?

Life cycle of a software bug
Life cycle of a software bug

Once you have attempted to replicate the bug, you can log in or register with Bugzilla. As your registered email address will be visible to other logged in users, consider creating a free email account to register with Bugzilla. Bugzilla notifies you of changes to your bug report through email. Before you file a bug report, it would be helpful to see if a report is already filed about the bug you found. This reduces the chances of people duplicating work on the same issue. When you file a bug, Bugzilla checks for duplicates, but you can also spend time independently searching.
If you find a similar report, see if you can add more information than what was originally reported. For example, the original report may be from an older version of MediaWiki, so it would be helpful for you to add a comment that the bug still appears, and to list the newer version, if you can. Maybe the original version does not have steps to reproduce; in that case, add a comment that your listed steps can reproduce the bug. If you do not find a duplicate report, you can go on to filing a new bug. You may end up unintentionally filing a duplicate report, and that’s ok. It’s better to report a second time than not at all.

Where does it belong?

When filing a bug report, the first thing you’re asked to do is choose a product to file the bug in. These products represent software projects, and it can be tricky to choose the right one. You have to consider what sort of error you have. Does the error seem to be with the MediaWiki software itself? The error could be in a MediaWiki extension.
Once you select a product, you’re brought to the page where you enter information about the bug. Here you can go through the components associated with the product you chose and read their descriptions. If the bug doesn’t seem to fit into any of those components, go back and select another product and look through those components. If you’re still not sure or you’re in a hurry, file the bug in the MediaWiki product and the General/Unknown component (MediaWiki > General/Unknown).
If the problem doesn’t seem to be with the MediaWiki software but with the configuration of a Wikimedia site, you should file the bug in Wikimedia > General/Unknown. Filing a bug in the right product and component helps developers address the bug sooner, because developers working on that specific component usually monitor incoming bug reports. However, bug triagers will move misplaced reports to the right product and component, so do not worry.

What does it say?

Now you should write a summary of the bug you found. Be specific in writing your summary. Vague, generic summaries like “Does not work” or “Feature request” are not helpful to get a quick idea what your report is about. Your summary is what developers, bug triagers, and other reporters will see when they are looking through bug lists in a component or that have been returned as search results.
As stated above, when you fill in a summary, Bugzilla lists possible duplicates. If you see a similar report, follow the steps above and comment if you have some new information to provide. If you don’t see a duplicate at this point then you can continue on and fill in a description. The description is where you can elaborate on the problem described in the summary. Here you list your steps to reproduce, what you expect to happen, and then what actually happens. You can also list other details like what browser you’re using if it seems like it is relevant to the report. Clicking the Add an Attachment button below the description will allow you to attach a file, e.g. a screenshot, to help enhance the quality of the report. Once you feel you have described the problem sufficiently, you can click Submit Bug.

You’re done!

Alright! You filed your bug! It may not be perfect, but that’s no problem. There is always somebody to help and improve them. You can look forward to receiving bug mail to keep you up to date on changes, which includes status changes and comments, with your report. Check your user preferences in Bugzilla to view and update what changes trigger an email. You may get comments requesting more information to help diagnose the issue. If you want to see an example of a developer fixing a bug, check out this video of a bug getting fixed.
Valerie Juarez, Bug Management Intern

Archive notice: This is an archived post from blog.wikimedia.org, which operated under different editorial and content guidelines than Diff.

Can you help us translate this article?

In order for this article to reach as many people as possible we would like your help. Can you translate this article to get the message out?

9 Comments
Inline Feedbacks
View all comments

Thanks for writing this – We should probably link to this from https://www.mediawiki.org/wiki/How_to_report_a_bug

[…] first is ‘How to create a good first Bug Report‘ and was published this Monday. It gives an overview of what we look for in a bug report, […]

GoingBatty, perhaps your browser is configured to block images loaded via HTTP on HTTPS pages? I have changed this thumbnail to be loaded via HTTPS – try again and see if it works now.

As I understand, nothing has changed. If a Wikipedia user is motivated enough to register a bug, s/he still needs to create… *yet another account* ! Even if s/he has already created a Wikipedia account ; even if s/he has already created several accounts — because each wiki lives alone in its own bubble. A Wikipedia developer has recently asked me to register a bug in this *yet other* system. It was not possible, it required me to create *yet another account*, and I did not do this. Because of two reasons. Because the process is too complicated — understand it as : I am lazy. And because… Read more »

“Your comment is awaiting moderation.”
Oh yes, some moderation ! No strong ideas, no ! And so great the censorship !

Ideas, now. StackExchange uses its Meta system to receive bug reports and feature requests and discuss them. See http://meta.ux.stackexchange.com and http://meta.stackoverflow.com . This kind of system is much more adapted. Contrary to Bugzilla, it does not pollute our mail-box with dozens of e-mails per day, but instead it has a nice process of notifications.

In comparison, Bugzilla is an antiquity.

Hi Nicolas, thanks for your comments. Bugzilla will require a separate account until somebody fixes https://bugzilla.wikimedia.org/show_bug.cgi?id=14487 , and personally I don’t consider that necessarily bad. Not sure what’s complicated about entering your email address on Bugzilla, receiving a password, copying it, going back to the browser and entering it, but maybe you refered to Bugzilla’s user interface? If “Wikipedia needs too be much more open about its bugs” then I’d be interested to hear how to be “more open” and what that is meant to mean. To me, Bugzilla *is* open (you only need an account for entering comments or… Read more »