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:
- 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.
- Clear all caches.
- 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.
- 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:
- Create a new number field that uses a textfield widget. Set it up to be a single value field that is required.
- 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.
- 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.