TROUBLESHOOTING: Debugging date and calendar problems

TROUBLESHOOTING GUIDELINES

Note

Do not use the README.txt file for D7. It is out-of-date. If you use the sample code there you will have big problems because that code is for D6.

More ideas about troubleshooting and creating useful bug reports is in an article I wrote for Lullabot: http://www.lullabot.com/articles/how-solve-all-your-problems.

1. Before reporting a bug, *ALWAYS* try the latest -dev version of the code (both Date and Calendar, if you use Calendar), and also the latest dev versions of Views (and in Drupal 7 you also need the latest dev version of CTools). Also be sure you are using the latest version of core. Many times people report problems that are already fixed in -dev and they could immediately start using the working code instead of sitting on their hands waiting for someone to respond to their issue.
2. Run update.php. Be sure to watch carefully to see if there are messages that you need to re-run it. Some updates that are dependent on other updates have to be aborted the first time or two. You may need to run update.php several times until you quit seeing messages to re-run it.
3. Clear all caches. Go to the Modules list in the administration section and submit the page, or in D6 go to the Performance section of Site configuration. In Drupal 6, be sure to clear all the Views caches by clicking on the 'Clear cache' button in the Views Tools tab, and also unselect the option to use cached data.
4. Edit your date fields. Go to the Manage fields screen for each of your date fields and edit the date field, 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.
5. Edit your views. Pull up each view that has a date field in it, or any views you are having trouble with, and edit each date field, argument, filter, or sort. Double-check that all the values look reasonable and re-save the fields and the view itself.
6. Check the ctools object cache If your problem revolves around a view that seems to have broken handlers or invalid elements, see if there is an entry with that view's name in the ctools object cache. There is no safe way for Date or Calendar to clear that cache, but if you have problems with a view you should get rid of any entries for that view in that table.
7. Search if your issue is already reported, if you still have trouble. If you are seeing an error message, do an advanced search on a few key words from the error message.
8. Try reproducing your issue on an new & clean Drupal installation with a minimum of installed modules and minimal configuration changes. Proving your issue can be easily reproduced *WILL GREATLY* increase its chances that it will be addressed in a timely manner. In fact, this is probably the #1 thing you can do to speed the process of resolving an issue. Document and report all the steps needed to reproduce the issue. This will help the maintainer both verify the problem, find a solution, and then verify the solution. This may seem like a lot of work you might not have time for. But, the maintainer must do this for LOTS of other issues too. By doing this, you save time for the maintainer so they can work on the fix instead of spending time just verifying the issue.
9. If you've done all that and you can't find a similar issue, open a new issue and be sure to say you have already done all the troubleshooting steps. Follow this guide for creating good, useful issues. Note that the new issue SHOULD be filed against -dev, since you already tested against -dev... right?

About The Latest Code

Official releases like 2.0 and 2.1 (with the green background on the project page downloads section) are only old snapshots of the -dev code at one moment in time. Once released, they are never again modified. So, the only time an official release is 'the latest code' is at the moment it is released. It doesn't matter how old an official release is, even if it was issued today, if there are patches committed since it was released, those patches are only in -dev. The -dev version is ALWAYS the latest code.

The -dev tarballs & zip files on the d.o project pages are updated every 12 hours, so they only include patches committed before the they were created. If a new patch is committed today, it is probably *not* in the project's tarball, even if that tarball has today's date on it. The only way to be sure you have all of today's patches is to wait for the first tarball created tomorrow. However, you can always get the latest code directly from the git repository, which is updated immediately.

You should usually use the official releases (the ones with the green background), but if you have a bug you may need to upgrade to a -dev release to pick up the bugfix (or to test that fixes your bug).