Last updated October 28, 2012.
This page details the process for creating a well-crafted issue report. For a drier description of the fields associated with an issue report, refer to Issue submission form fields.
About the issue queue itself
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.
Before you open an issue
Existing Drupal Core issues
Existing Drupal Core issues have a different protocol. For more information, refer to Write an issue summary for an existing Drupal Core issue.
Please review the Issue Summary Template Standards for exact format on how to write issues.
Filling out project information
In most cases Project will be automatically populated. Make sure this is correct. 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.
If you file an issue directly from your drupal.org profile, you will need to select an item from the Project drop-down. To help you determine which item to select, here are the possible scenarios your issue falls under:
- If you have an issue with a contributed module, theme, translation, or installation profile you downloaded from drupal.org, select it from the list.
- Select the "Documentation" project if you have found an issue related to information on a Handbook page on drupal.org.
- Select the "Drupal" project if you are reporting a problem with the core parts of Drupal, or with some documentation you found on api.drupal.org (which is embedded in the Drupal core code).
- Select "Drupal.org web masters" for page delete requests, such as Spam and test handbook pages.
Choosing a version for a bug
When reporting a bug, be sure to specify the version where you found the bug. To best help the developers, upgrade to the latest official release and verify the bug still exists. If the bug still exists in the latest official release, upgrade to the latest development version (-dev) and verify the bug still exists there (it may very well be fixed in -dev, but not yet made it into an official release). Ideally, all bugs should be filed against -dev as all code changes are only applied to -dev.
Choosing a version for a feature request
When making a feature request, always choose the development version (-dev). For Drupal core new features will only ever go into the latest development version (the next Drupal release). Features are not added to stable core releases. For contributed modules this will depend on the maintainer.
This will vary by project, as each project may choose their own list of components to present. Make a decent guess as to the right Component of the Project. 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.
If you are reporting an issue against the Documentation project, the Documentation issue reports page has information about how to choose the component. For other projects, choose a component that conforms most closely matches the problem you are seeing.
Try to determine the Category, Priority, Assigned, and Status values.
A category determines the broad grouping under which your issue falls.
Defining the category for an issue
- Bug Reports are for situations where the software does not work as was intended by the programmer.
- 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'.
- Feature Requests are for situations where the software works as designed, but the design can be improved. Before making a feature request for Drupal core, please read Criteria for evaluating proposed changes.
A caveat about requesting new features
New features are generally only accepted for the latest development version code if 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.
- 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. However, for Drupal core, it is recommended not using the issue queue for support, but instead one of the other ways mentioned.
Categories for the Documentation project
If you are reporting an issue in the Documentation project, see the documentation descriptions as they are slightly different from most projects.
Priority is used to define the relative importance of your issue to the project and other issues in the queue. It does not define the importance of the issue to you personally.
Defining the prioirity of an issue
- Critical is used to designate broken functionality that makes the project unusable. "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.
- Major is used for issues which have significant repercussions, but do not render the whole system unusable.
- Normal is the default priority applied.
- Minor is when there is no urgency to solve the issue.
More detail in Priority Levels of Issues.
The Assigned field helps keep track of the person working on a particular issue by username. You may leave this field as "unassigned" (the default value) if the issue is still seeking an owner. 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 your username.
Each Drupal.org issue has a status assigned so that we can tell at a glance what progress has been made with each issue. 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.
Your title should be descriptive and concise.
Example: Compare these two titles:
SITE BROKEN YOU MUST FIX NOW!!!111!!
Admin-Modules Page Blank After Installing Module Foo
Analysis: 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 follow up. 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".
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
Example: Compare these two bug reports:
MY PAGES ARE BLANK!!! I AM ABOUT TO DELETE DRUPAL FROM MY SYSTEM!!!
Steps to repeat:
1. Download Module Foo
2. Un-compress foo-6.x-x.x-tar.gz into modules folder
3. Visit admin/modules page in site
User sees the modules page and can enable the module Foo
Page is completely blank. Checking in the Apache Error Log showed this error:
Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 418591 bytes) in /path/to/drupal/modules/foo/foo.module on line 42
Analysis: 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, they 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 finding the problem relatively easy for the developer.
If the Category selected was 'Bug Reports' or 'Support Requests' there is additional information that the user can provide to the developer. Information about the server environment such as which operating system, database, web server, php version, php error reporting level, and Drupal version is being used. In addition check the log files for the web server, and database server. Here is an example presentation of this information for a bug report.
OS: OpenSUSE 11.4
Database: MariaDB 5.1.44
Web Server: Apache 2.2.17
PHP error_reporting = E_ALL
Last error from the Apache error log:
ERROR: Use of undefined constant T_COMMENT - assumed 'T_COMMENT' on line 127 in /www/d7.2_test/sites/all/libraries/grammar_parser/engine/parser.inc (Notice) Fatal error: Call to undefined function token_get_all() in /www/d7.2_test/sites/all/libraries/grammar_parser/engine/reader.inc on line 3135
For some more general tips on writing helpful descriptions, also see the non-Drupal specific How to Report Bugs Effectively.
It is often very helpful to provide attachments to an issue or a comment/follow up of an issue. Attachments can be code (e.g., a patch to correct the problem) or they can be media files (e.g., 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.
Note: The Issue Report forms allow you to upload files with only certain file extensions; which are jpg, jpeg, gif, png, txt, xls, pdf, ppt, pps, odt, ods, odp, gz, tgz, patch, diff, zip, test, info, po, pot, or psd. If the file you want to upload does not have one of these extensions, you will not be able to upload it.
You can freely type any tags to add information to your issue. However, tags are most useful if they are used by multiple issues, because people can click on a tag to find other issues marked with that same tag, and they can also use Advanced Search to search for issues by tag. So, when using tags, try to choose tags that others have already used (which you will see as you begin typing your tag).
Some commonly-used tags:
- Novice: Issues that someone new to Drupal could help with (easy to make a patch for)
- ui-text: Issues involving updates to user interface text
- Help text: Issues involving updates to help text within Drupal
- API change: Issues involving changes to the Drupal API
- Markup change: Issues involving changes to HTML tags and attributes that are generated within Drupal (as opposed to the text within the HTML)
- The Documentation issue reporting page lists the tags that are specific to documentation issues.
More information on tags can be found on the page Adding tags to issues.