HOWTO: Make A GOOD issue report

Drupal makes use of the Project issue tracking module combined with the Project module to keep track of issues that are found in Drupal Core software, Modules, Themes, Theme Engines, and Translations. This system tracks several pieces of information about each issue but also leaves a large empty box for you to enter your own bug report. If you want your bug to get fixed, it is extremely important that you take the time to enter the proper information into these fields.

You should also see How to troubleshoot Drupal for self-help steps to do BEFORE raising an issue.

Project Information

Make a decent guess as to the right Project and Component. Sometimes the correct value can be unclear, but if you make an effort to get it right that helps. Your issue may be updated by others if your first guess was off.

Always specify the exact version where you found a bug. Choose the latest development version when you make a feature request, because all new features will go into latest code. For Drupal core new features will only ever go into the latest development version. Features are not added to stable releases. For contributed modules this will depend on the maintainer.

Issue Information

Try to determine the Category, Priority, Assigned, and Status values.

Category:

• Bug Reports are for situations where the software does not work as was intended by the programmer.
• Feature Requests are for situations where the software works as designed, but the design can be improved.
• Tasks are for something that just needs to get done, where the parameters are well understood. Whitespace repairs, adding translation function support, fixing spelling errors etc are usually just 'tasks'.
• Support Requests are for situations where you wish to ask about a specific component. Support Requests can seem redundant with the forums, IRC, and mailing lists, but these are a good way to ask a question at a targeted audience (the module maintainer) and may result in extended or clarified documentation.

Note that new features are generally only accepted for the latest development version code unless they are very important. Even if it seems important to you, it has to be important for a large number of sites to be worth creating a fix for a currently released version of Drupal. You cannot get around this rule by simply labeling a feature request as a bug request. If you want to get a feature applied to a released version of Drupal you need to make the case that it is important, affects a large number of sites, and ensure that the code changed is stable.

Priority: the priority field is an easy one to abuse. Generally, Critical should be reserved for the most problematic and important issues. Abuse of the Critical field will likely get your issue ignored by a developer and that's the last thing you want. Normal and Minor priorities are both fine to use. More detail in Priority Levels of Issues. Priority is about the status of the issue on the module - not about its importance to you personally.

Assigned: the Assigned field helps keep track of the person working on a particular issue. If you are working on the issue - e.g. you are writing a patch to fix it - then you should set the issue as assigned to you.

Status: Status is one of the most often overlooked fields. Many developers have filters set to look for issues in certain statuses, so changing this field inappropriately can lead to your issue getting ignored.

Issue Details

Title: you want your title to be descriptive and concise. Compare these two titles:
SITE BROKEN YOU MUST FIX NOW!!!111!!
and
Admin-Modules Page Blank After Installing Module Foo

The first title doesn't explain the problem and tries to impart a sense of priority. The priority should stay in the priority field. The title is for describing your problem, and while "SITE BROKEN" may be what you think of your site it doesn't help a developer when they see three bug reports with different problems all with the title "SITE BROKEN". The second title succinctly describes the specific problem with the site and a possible cause. This makes it easy for the developer to keep track of the bugs in their queue. If you look at many of the issue queues you will see dozens or hundreds of issues. Having unique titles that are descriptive makes a specific issue stand out as easier to work on among the rest of the issues.

Also note that the project issue titles do not behave like a forum thread. Changing the title will change the title of the whole issue, not just your followup. This is useful for renaming a vague issue into a more descriptive one but it makes things worse if it is used to title issues like "I'm getting this too".

Description: The Description field is wide open which leaves you a lot of space to say a lot or a little. The Description takes the title one step further. Generally speaking, the majority of the time spent fixing an issue is spent on understanding the problem and finding the cause of that issue. The goal of the description is to state the exact set of conditions that cause a problem and the resultant undesirable state of the system so that the developer spends as little time as possible understanding your situation. Your issue should reflect the

• repeatability of the problem - whether it is easy to repeat or happens randomly
• steps to repeat - what you think caused the problem, ideally these steps should be repeated until they are as simple as possible and still cause the problem
• desired outcome of the steps - that is, what you WANT to have happen
• actual outcome of your steps - this is the essence of your problem

Compare these two bug reports:

MY PAGES ARE BLANK!!! I AM ABOUT TO DELETE DRUPAL FROM MY SYSTEM!!!

and

The first bug report is relatively useless because it forces the developer to waste their time asking questions and guessing at the possible problem. The second one communicates the problem precisely and concisely. The user has described a specific set of steps that they took, the have stated that it is repeatable in their tests, and in addition to the desired and actual results they provided an exact error message from their system. This makes the developer's job relatively easy to try and find the problem.

Attachments: It is often very helpful to provide attachments to an issue or a comment/follow up of an issue. Attachments can be code (eg. a patch to correct the problem) or they can be be media files (eg. images). When reporting any kind of user interface problem, it is often very useful if you provide a screenshot or a video that demonstrates the problem or solution. Likewise, if you provide a patch that changes some part of the user interface, it is helpful to reviewers if you provide a screenshot of how your patch changes the interface.