by Karen Stevenson on June 2, 2011 // Short URL

How To Solve All Your Problems

Using the Drupal issue queue to your best advantage

OK, maybe not all your problems... But at least your Drupal problems. The Drupal ecosystem is composed of several thousand contributed modules, each one maintained by one or more volunteers. When things go wrong, as they will, you need to know how to get your problems resolved, and that requires understanding how to get the most out of the Drupal issue queues.

Before You Report Anything

Before reporting a bug, always try the latest code to see if that resolves it (see the next section for how to tell which version is the latest). Many times people report problems that are already fixed in the latest code and they could immediately start using the working code instead of helplessly waiting for someone to respond to their issue.

Go to the Project Issue Queue

Each Drupal project has its own issue queue. You can get to the project page by typing the project's url, like http://drupal.org/project/cck or http://drupal.org/project/views. Be sure to read the project page. Sometimes there are messages there about known issues.

'Latest Code' Means 'Development'

The project page will have a list of 'Releases'.

You should usually use the official releases (the ones with the green background), but if you have a bug you will need to try the development release (the ones with the red background) to pick up the bugfix (or to test if that fixes your bug). If you don't see a development release on the project page, you can click on the link that says 'View all releases' to see if there is a development release (a release for your version of the code that has '-dev' appended to the name). Testing the development release does not mean that you need to switch your production site to the -dev version, you should do this testing in a local or development environment.

Official releases are snapshots of the code as it existed at one moment in time. Once released, they are never again modified. So when bugs are fixed, they are fixed in the development version. The official release will not pick up the change. When you want to see if a bug is fixed, you need the latest code. When you need the latest code, it is always the development version.

Even the development release can be out of date. The development tarballs and zip files on the Drupal.org project pages are updated every 12 hours, so they only include patches committed at the time they were created. If a new patch is committed today, it is probably *not* yet in the project's tarball, even if that tarball has today's date on it. The only way to be absolutely sure you have a specific patch in a tarball is to wait for the first tarball created the day after the fix was committed. The git repository is the only place that is always guaranteed to have the latest code immediately.

See if Your Problems Are Already Solved

Anytime you pull down a new version of the code, do the following:

  1. Immediately run update.php. Be sure to watch carefully to see if there are messages that you need to re-run it or that anything went wrong.
  2. Clear all caches.
  3. If the problem is related to a CCK field (in Drupal 6) or a Fields field (in Drupal 7), go to the 'Manage Fields' screen for any field you are having trouble with, double-check that the values all look reasonable, and re-save it even if you don't change anything. Also go to the 'Display Fields' screen, double-check all the settings there, and re-submit that screen.
  4. If your problem has anything to do with Views, be sure to clear the Views caches by clicking on the 'Clear cache' button in the Views 'Tools' tab. Edit the problematic view, and look at each field, argument, filter, or sort. Double-check that all the values look reasonable and re-save the fields and the view itself.

Then see if your problem still exists on the latest code.

Find the Issue Queue

If you still have a problem, you need to see if the problem is already reported. In the right sidebar of the project page you will see a block that looks like the following:

Type a search term in the box, or just click on the 'Search' button to go to the full issue queue. Then filter the issue queue down to the major version you are using. You don't want to see issues about the D6 version of the code when you are using the D7 version. Keep in mind that there might be a closed issue that addresses your problem, so look at all issues, including closed ones (issues get closed after the bug is fixed).

Search to see if your issue is already reported. For instance, if you are seeing an error message, do an advanced search on a few key words from the error message.

If you can't find a similar issue, open a new issue and be sure to say you have already taken all these troubleshooting steps. Note that the new issue should now be filed against the -dev version, since that's what you're now using ... right?

One Issue Per Issue

In some places, you would expect to open an issue and dump into it every problem you know about.

The Drupal.org issue queues don't work that way. We report each problem as its own issue. This way other people having the same problem can more easily find it and see what they need to do, or provide more information about the problem.

This is really important for maintainers. They don't need to see a lot of unrelated information, they need to see information that is specifically related to that one issue. And when it is fixed, they can close the issue and move on to another one.

Make the Title Descriptive

The title of the issue is really important. Maintainers often scan the titles to decide how to handle it. Other users scan the titles to see if there is already a report about their problem.

A bad title would be something like 'Everything is broken!!!!!'. The only way to tell what that report is about is to read the whole issue. A good title will provide a useful summary of the heart of the issue, like 'Multiple value nodereference fields broken in some views'. A title like that makes it possible to tell at a glance if this issue might be related to your problem.

Don't Say Too Little, or Too Much

Well this sounds impossible, but bear with me. 'Too Little' means terse reports like 'Everything is broken' or just pasting in an error message with no context about where you were or what you were doing when you saw it.

Remember that there are hundreds, maybe thousands of possible combinations for the things that might go into a field or a view. Saying 'I created a view and added a field and it broke' is way too little information.

'Too Much' means providing a complete history of everything on the site and all you hope it will accomplish, where you have to wade through several paragraphs to get to the place where the problem is described.

The goal is to provide enough information that the maintainer could start with a blank slate (they don't have your site or your data, after all), and get to a place where they could see the problem you are seeing. A useful report would look something like:

  1. Create a new number field that uses a textfield widget. Set it up to be a single value field that is required.
  2. Create a new view. Make it an unformatted list of fields. Add this field to the view and set it up to use the default formatter.
  3. When you display the view you will see the error 'XXXX'.

Don't Switch Versions

Stick with issues that use the same major version you are using. If you are using the Drupal 7 version and you see an issue that looks similar for Drupal 6, don't just jump in and say 'Me too' and switch the version on the issue. It is highly unlikely that the problem is actually the same from one version to another, and changing the version pollutes the issue, making it much harder for the maintainer to do anything with it.

In the above case, if you see a similar issue in another version but nothing in your version, create a new issue, marked with the version you are actually using. In the issue you can make a link to the other version's issue. If they are actually the same, the maintainer can say so and mark one as a duplicate, otherwise they can stand as separate issues that may (and probably do) have different implications and fixes.

Don't Re-Open Closed Issues

If you find an old, closed issue that looks similar to your problem, generally you should not re-open it. Especially if it is very old and very long. The exception is if the issue was just closed recently and you have determined that something that was supposed to be fixed is actually still broken in the latest code. In that case you can re-open it with the explanation that you have tested it in the latest code and are still seeing the problem. Make sure you describe how you determined that it was still broken.

A corollary to this is not to post questions on closed issues. Issues that are marked 'fixed' or 'closed' or 'duplicate' all fall off the radar of the maintainers. They often don't even look at those issues any more. Post questions on new or open issues.

Profit!

If you follow all the above steps, you will either:

  • Discover that your problem has already been solved,
  • Find an existing bug report you can follow to see when the problem is fixed -OR-
  • Create a new bug report designed to provide the right information to help the project maintainer get the problem solved.

Congratulations! You're ready to leverage the Drupal.org issue queues. Obviously, there's a lot more to troubleshooting and problem-solving than bug reports and patches. By using the tools available on Drupal.org, though, you'll be able to leverage the work of thousands of other developers and site builders -- and they'll benefit from your work, too.

Karen Stevenson

Senior Drupal Architect

Want Karen Stevenson to speak at your event? Contact us with the details and we’ll be in touch soon.

Comments

merlinofchaos

By default, Drupal only

By default, Drupal only searches open issues. But if the issue has already been fixed, it might be closed and duplicate issues won't show up. Many people DO search and end up filing a duplicate issue anyway because they didn't realize that all the issues on the topic are marked closed or dup.

Reply

Jody

Agreed

Agreed, that was my only minor disagreement with these great guidelines. Only the module maintainers really care about seeing a list of only open issues and other folks should really be looking at all issues. It's great that both open and all issues are listed so you can at a glance gauge the health, but we should encourage users to look at the full list.

Reply

KarenS

Good point

That's true. I changed the wording a bit to encourage people to search closed issues as well.

Reply

latulipeblanche

Status - Any -

Tnx for this article.

I think, to help the Maintainers not to have to much issues about the same problem, and to push users to search in "ALL" issues, it would be better to set "Search for: Status: - Any -" as default.

Reply

Mike Ryan

Documentation Appreciated

Thanks for writing up basic documentation like this. This is the stuff that is absent that will allow more people (like me) to effectively get involved.

-M

Reply

S1L

fuzzy feelings

Reading into and contributing to the project issues helped me out a lot in the past.
Part of the reason I do it for is the warm fuzzy feeling you get when you solve someone else's issue :)

Adding relevant information to existing issues (created by others) also helps with solving issues. It may not be a concrete solution, but it may help lead to one.

And let's be honest here: interaction with like-minded Drupallers is fun :)

Reply

Dave Reid

Tagging issues

Unless you have the specific purpose of being able to list issues from different projects together, then you should not add or change any 'Tags' in your issue/comment. If you're not sure, then you shouldn't be adding or changing any tags.

Reply

Oscar

Good advice

What do you though if a particular module has a fix in dev but can't/won't roll out a recommended release in a timely manner.
I end up patching modules if there is a patch that fixes it, but that can become a management nightmare.

Reply

Arlin Sandbulte

Great Article

Great Article, Karen!
This really should go in the Handbook somewhere ... where it can be lost forever :-\

Reply

KarenS

I wanted to get some attention

Yeah, if I just created this on drupal.org odds are none of the people who have seen this article would have even noticed. In fact, I have posted numerous docs on drupal.org telling people how to debug Date, Calendar, and CCK problems, etc, and I don't think anyone looks at them.

Posting this on Lullabot gets it into the Planet and more people see it. I'm happy to also put something on d.o.

Reply

Rick Manelius

Development Versions

Hi Karen,
This is a great article. Lullabot seems to be on a tear lately with well put together overview material. I agree with other posters that this should be moved/cited on Drupal.org.

My only disagreement would have to be with dev versus production releases. With some modules (date comes to mind), 'dev' because the new 'production' and you almost couldn't run a production site without being on the dev version.

Other modules, however, stick to the release/dev numbering more strictly. So for my production sites (which admittedly only have up to 5,000 active users), sticking with a mix of production and development packages is a necessary evil.

In a perfect world, every module maintainer would have the time to use simple test and have this clear distinction. Since they don't, this onus gets dropped on the people using the modules to keep this all straight in our heads!

Reply

dalin

I can't tell if @Rick is

I can't tell if @Rick is being passive aggressive, or if he just doesn't realize that Karen (author of this article) is also the author of Date module.

Reply

Rick Manelius

My Sincere Apology

Ouch. My sincere apology to Karen S. I still stand behind what I said in that there is some major difficulty in keeping in sync with production and development modules and its no slight to her personally because a) like views, the date module is almost essential to Drupal b) time zone conversion, daylight savings, etc is not easy to track among the 3 types of time storage.

So like the other popular modules, it have an issue queue a mile long. Module maintainers like Karen then must (only having 24 hours in the day) make choices about what is in development versus rolled into a full release.

This is clearly a difficult dance, and everyone's standards are different. If you want forever to roll a new release candidate, everyone is essentially on dev and it's pointless to stick to that. If new versions roll out willy nilly, then even the release version is risky, but at least everyone is on the same page.

I'd like to at least stand by my original compliment as well in that I totally agree with the sentiment of this article and believe it should be rolled into official documentation. As for coming off as jerk... I'm sorry and wish I looked at my comments another time before hitting publish.

Reply

KarenS

No offense taken

Yes, maintainers have a lot of things to dance around. I don't want to roll an 'official' release when there are still lots of unresolved issues in the queue, but when the queue is long you can't fix everything, so I have to keep trying to find a point where things seem fairly stable so I can tag a release. Immediately afterward someone will point out that something critical is broken, so the dance starts anew.

Sometimes you end up using development on production, so you can pick up fixes. Sometimes you can get away with applying a specific patch until the fix gets into an official release. Sometimes you can just live with some oddities until the new release gets cut. I just wanted to point out that the 'ideal' is to use official releases.

Reply

Rick Manelius

The Bleeding Edge

One more point I'd like to add: having looked at my SVN history a bit more closely, I can say that I've almost never used the recommended release for views/ctools/panels, even on production sites.

If a feature is broken on a production site, I find most of my clients go into panic and (unfortunately) one may just have to take the risk and stick with development releases until things get stable. But with modules that are either a) extremely new, b) extremely popular, or c) add new features rapidly (views), it's almost mandatory that you stick with dev.

So like Karen says, try dev first. But then what happens next? Many of us need to then go with dev! Which is fine, because one person's dev might be another persons recommendation. Again, it becomes a matter of preference again and that is not standard across all maintainers.

I'll shut up now :) I was trying to be helpful/insightful, not hurtful or know-it-all.

Reply

shekhar

need help

hi
i have 1 problem i am working on bartik plus theme but i am not able to remove superfish menu which is appearing in the footer region so can you guide me , how can i come out of this problem
Drupal 7

waiting for u reply

Thanks
shekhar

Reply

Anonymous

Articles

This is good article. the topic how to solve all problem is a good concept.. is it possible to solve all problems? can any one tell me..
thanks..
----------------
Arrow

Reply

ketty

Great

This is such a great resource that you are providing and you give it away for free. Great post...
thanks for sharing the info....iphone 5

Reply