Upgrading from Drupal 5.x to 6.x - The Survival Guide

Upgrading Drupal core within the same release series is a fairly painless process and should be done whenever a security update is out. On the other hand, moving an existing site with a long history of content, personalized theming and custom modules from 5.x to 6.x can easily turn into a complicated and time-consuming process should you not do it right.

Tirdad Chaharlengi, Senior Developer
#Drupal | Posted

Upgrading Drupal core within the same release series is a fairly painless process and should be done whenever a security update is out. On the other hand, moving an existing site with a long history of content, personalized theming and custom modules from 5.x to 6.x can easily turn into a complicated and time-consuming process should you not do it right.

There already are a number of informative posts out there that cover the general process of this upgrade, but they often restrict themselves to vanilla Drupal installations, with little customization or use of 3rd party modules. I've tried to assemble a decent selection of resources from that category but also some tips that provide you with more specific information about often ignored aspects of the upgrade process.

First off, there are some general pointers that are always good to go over:

1. Back up your data like there's no tomorrow, and at every step
Aside from the mandatory initial backup, make sure to take a snapshot of your DB and your files every time you go through a step without things falling apart. Think of it as a slightly more tedious quicksave. It will make the whole process much less stressful if you have something to roll back to.

2. Plan ahead and do an audit of your 3rd party modules
Time for the great Drupal Purge of 6.x: do you really need to use that module there? Is it even available for 6.x? If so, is there an upgrade path for it? The less extra modules you have, the less time you will have to spend dealing with upgrading them. If you want to get rid of a module before the upgrade, make sure to actually uninstall it through admin/build/modules/uninstall before you delete it.

3. Upgrade to the latest / correct 5.x version of your modules
Many modules require you to upgrade to the latest 5.x version (or a specific one) before you go ahead with the transition over to 6.x. This includes CCK. If you did your research during the previous step, this is just an extension of that.

4. If you have Update Status, don't forget to uninstall it
It's been integrated into core for 6.x, so disable and uninstall it once you're done with updating the 5.x modules.

OK, enough with that for now, as I really want to skip to some of the less obvious details. Here are some highly useful links to help you deal with that initial aspect of the upgrade process:

Upgrading from Drupal 5 to Drupal 6 on Learn By The Drop
How to Upgrade from Drupal 5 to Drupal 6 on Be Circle
Upgrading from Drupal 5.x to Drupal 6.x - Tutorial on Drupal.org
Upgrading Drupal can become a trainwreck on hiveminds.co.uk (or why your need someone experienced with Drupal to do this for you)

With that out of the way, here are some things you may have to deal with:

1. Views
Your 1.x Views will not magically carry over to Views 2.x once the module is upgraded. There is a conversion tool that's accessible through Tools > Convert but given that the process is not fully reliable and may result in missing fields and filters, this is not the best approach to take unless you know what you're doing. Rebuilding your views is strongly recommended, and given all the extra perks of 2.x, you may find a way to use this opportunity to re-think some of your views (ie you now have the attachment display, no more bizarro-cuisine to deal with featured/promoted nodes).

2. Theming
Any custom theme you may be using will not be noticed by Drupal 6.x until you create a themename.info file in its folder. This post provides more details on the full process of getting your theme up to 6.x norms.

3. Custom modules
You will have to modify any custom modules you have written to factor in the changes made to function signatures. Here are some good places to look for this:
Upgrading your menu system from 5.x to 6.x
Converting 5.x modules to 6.x

4. L'Ecran Blanc de la Mort
You may get a PHP fatal error once you start working on your custom theme or on your custom module(s), usually because a function call is made somewhere with the 5.x signature. However there's an even more perverse scenario than that when you've got PHP code in your database-stored blocks (Pro-tip: don't put long chunks of code in blocks in general, generate them with a custom module and then use those blocks). Irakli covered this on his blog and provides you with you quality debugging advice, so go read that there.

This is only a (not so) brief review of the upgrade process, and many of these points may or may not even apply to your specific site depending on its complexity and use of Drupal's capacity for customization. That said, an upgrade from 5.x to 6.x is really not something to be lightly messed with, specially if you're a casual user. A certain level of Drupal experience will considerably smoothen the process, but following the advices above will save you a lot of grief.

Tirdad Chaharlengi

Senior Developer