Skip to main content

Blog Post

What's your issue?

When working with Drupal it is very important to keep one thing in mind: all progress happens through the site’s issue queues, Drupal’s equivalent to support tickets. Each project, including every module, theme and Drupal core itself, has its own dedicated discussion area where issues are discussed - a queue of issues. Everything from bug reports & fixes, to feature requests, to support requests and to documentation improvements, they all go through this central communications channel. This centralized communication is a great boon to project maintainers as all of this is in one location, but it can be a bit daunting to the beginner.

Simply put, if a site runs into a bug in a contributed module, it isn’t clear how a module should be used, or maybe a new feature could help improve it, the module’s issue queue is the best place to start looking for answers.

The general rule with issue queues is that each topic should have its own issue rather than bundling together multiple topics into one issue. Adhering to this rule helps keep conversations short (relatively speaking), on topic and, in theory, quickly lead to a resolution. That said, most of the more popular projects will have page upon page of issues covering the whole gamut of possibilities - “this module doesn’t work”, “I can’t understand how to make it work,” “if you change it like this then we can also do all this other stuff,” “please add Dave Reid as a co-maintainer,” “there’s a typo in the README.txt file,” “that link should be red not blue,” “that link should be blue not red,” and on and on. With possibly hundreds if not a thousand or more (!) active discussions it is very important to know how to find the issue relevant to an individual situation.

“It started with a search”

To badly paraphrase Hot Chocolate’s early 80’s hit, “it started with a search.” Drupal has a reasonably good search engine built in and the issue queue puts this to great use. In the interest of improved usability each project’s issue queue can be searched directly from the project’s main project page itself - there’s a small search box in the right sidebar right under the list of maintainers and this is the starting point for any search. Searching for an issue is simply a case of entering a few words in the search box and clicking the Search button.

Along with basic keyword searching the issue queue allows a variety of other filters to be changed to help fine tune the search results. During the course of discussion an issue will typically have its status changed from “Open” to “Needs review” once someone has provided a working patch, hopefully on to “Reviewed and Tested by Community”, aka “RTBC”, once said patch is verified to work correctly, to “Fixed” once the patch has been committed to the codebase, finally resting at “Closed (fixed)” once the dust has settled. There are additional issue statuses that provide further nuance to the discussions, e.g. “Needs work” for when a patch either doesn’t work or needs further polish, and “Closed (duplicate)” for when a topic already has an issue where it is being discussed. The status field becomes important when looking for a fix for a bug, if an issue’s status is “Needs review” then there should be a fix ready to test, if it’s “RTBC” then others have already tested the fix and it’ll be ready to go.

But wait, there’s more!

Several of the other filters are also worth exploring. As mentioned above, issues can cover a number of general categories – bug reports, feature requests, support requests, or a general task – so there’s naturally a filter for the issue’s category.

There is also a component field for issues. Unlike the other issue fields, the list of components can be customized per project thus some will have a length list of individual pieces of the project to help narrow an issue’s focus. That said, a good many just stick with the defaults – code, documentation, user interface, and miscellaneous. Because of this it’s worth considering that not all issues are assigned to the appropriate component or it may span multiple components, so this filter may or may not be very useful. Your mileage may vary.

Nuance

One of the filters is a little more nuanced than it may at first seem. As each project has a major version that matches the release of Drupal it is compatible with, the project release numbers include the Drupal version in their name, so instead of a module’s version being labeled “1.1” it be version “7.x-1.1”. The version filter on the issue queue will list every single release that is made for a project, even for releases that are no longer supported - yes, even back to the Drupal 4 days if the project is old enough. To simplify life it’s possible to simply select the corresponding Drupal release, e.g. “7.x” to search against all releases compatible with Drupal 7.

As if that nuance was insufficient it’s worth being aware of a standard practice in the Drupal community. When there are supported releases of a project for multiple core releases, e.g. Drupal 6 and Drupal 7, the standard practice is to first make the necessary changes for the newest release and then “backport” the change to the older release. In practical terms this means that it’s likely a bug being experienced in a Drupal 6 module will first have to be fixed in the Drupal 7 version and backported, thus it may be best to not limit searching through the “6.x” issues.

"One more thing"

As if all of that was not enough, there’s an Advanced search option that allows for multiple values for each filter to be selected at once. This makes it possible to search for either an bug report or feature request that is for the project’s 7.x-1.1 and 7.x-1.2 release but not the 7.x-1.3 release.

The advanced search page also opens up the chance to search issue tags, keywords that can be added to each issue. Issue tags are often used by project maintainers to identify bugs that are release blockers, related to specific use cases, etc. Additionally it allows searching the original submitter of an issue, the participants, i.e. anyone who commented on the issue, or even the person an issue is assigned to, making it possible to e.g. search for issues you started which was responded to by the maintainer.

Finally, one of the most powerful aspects of the advanced search page it is possible to search across every project with the same filters. The interface doesn’t directly provide a way to do this, but if the URL is changed from “project/issues/search/[projectname]” to just “project/issues/search” it will search all projects. Putting this with the standard filters and tagging makes it possible to find issues you submitted that need review, find i18n (internationalization) issues that Gábor Hojtsy participated in, or just stalk Crell.

Search Tips

From my few years working with Drupal, I’ve found it useful to first search for obvious words related to the change that’s needed, and, if nothing relevant is uncovered, then branch out to synonyms and related words. For example, are you looking for a “theming improvement” or a “CSS fix”?

An important tip is to not forget about discussions that have been closed, so remember to change the issue status filter to “Any” rather than the default of “Open” if nothing is found at first. Making this adjustment will also search closed issues rather than just active ones; with the long development cycles of some modules the appropriate topic may have been discussed several months ago or years ago and already resolved! This is particularly important when looking for bug fixes as the symptoms of a bug may actually be caused by something else entirely thus an issue reporting the symptom may be marked as “Closed (duplicate)” in deference to another issue focused on fixing the core problem.

After all of the searching is done, if an issue is found that matches the desired change it is important to read through the full discussion rather than jump to the punchline; doing so will not only help understand further detail about but also, hopefully, the views of the project maintainer and others on the topic. I’ve many times found alternative ideas I had not thought about while researching, in some cases leading to an even better solution than the original.

Go forth and search!

Additonal Resources

What's new in Drupal 8?

Webinar: Building Drupal Features

Damien McKenna

Meet team member, Damien McKenna

In his role as Community Lead, Damien directs internal initiatives that strengthen Mediacurrent’s commitment to open-source principles, collaboration, and sharing knowledge to strengthen the Drupal community. Regularly ranked as one...

Learn more about Damien >

Related Insights

Access icon Up arrow icon Drupal 8 icon Facebook icon - white Facebook icon - blue outline Facebook icon - yellow Hollow right arrow icon Hollow right arrow icon - white LinkedIn icon - white LinkedIn icon - hollow LinkedIn icon - blue outline LinkedIn icon - yellow Mediacurrent wordmark Quote icon Twitter icon - white Twitter icon - hollow Twitter icon - blue outline Twitter icon - yellow Youtube icon - white Youtube icon - yellow