How to Upgrade from Drupal 5 to Drupal 6 - Steps 3 and 4: Actual Upgrade and Testing
Today I finish up the series of articles about upgrading from Drupal 5 to Drupal 6. Earlier posts in the series included: Finally Time to Upgrade to Drupal 6, How to upgrade Drupal 5 to Drupal 6 - Step 1: Planning and Step 2: Getting Drupal 5 Upgrade Ready
The first few posts were all about getting you to the stage where you can actually go ahead and upgrade your Drupal installation. In 25 words or less, do rigorous planning and take several actions to prepare your Drupal 5 site for upgrade before upgrading to Drupal 6.
In this post I finally tackle the actual Drupal upgrade process and include some final thoughts on testing your success.
Before I get started, I just wanted to mention that you should always test your upgrade procedures before attempting an actual upgrade. If you have your own deployment methodology with version control and development and staging servers you will have some sort of process in place for "green lighting" a live upgrade. If you have such a process, follow your own best practices.
On the other had, if you don't yet have such a process in place, I would strongly encourage you to attempt your upgrade on a copy of your site before attempting an upgrade on your live site. Even after planning and preparation, there are any number of gotchas that might come along and its better to discover those during a test run. Even if the actual upgrade appears to go smoothly and error free, you may discover that your content (or the way you create content) didn't upgrade properly. Once again, it's best to catch problems and formulate solutions before attempting the upgrade on your live site.
Upgrading to Drupal 6
In the "Step 1" post, I encouraged you to read UPGRADE.txt. Since the writing of that article just a few days ago, UPGRADE.txt has been updated with some more information (such is the world of a fast moving open source community). As a result you may want to re-read that document if you've been reading this series as its been published.
Here I will go through the steps in the updated revision (January 15th 2009).
The first few instructions are fairly simple:
- Back up your site (see my notes in the previous post about backups)
- Log into your site as user 1
- Put your site into 'off-line' mode
- Switch your theme to "Garland"
Disable all Custom and Contributed Modules
In the planning phase you should have created an inventory / checklist of all modules you had installed as well as the sub-modules or components that were enabled. Follow your checklist and disable all of those modules in Administer » Site Building » Modules.
Because some modules depend on others, you may not be able to disable everything in one step. If a checkbox is 'grayed out' next to a module it means that another module depends on that module and is still enabled. You will first have to disable those dependencies.
Out with the Old and In with the New
The next step requires you to remove the old Drupal files from your installation directory. This includes all the files in the root directory (e.g. index.php, .htaccess etc.) and all the Drupal folders (e.g. modules, includes, etc.). Obviously when you do this your site will be completely inaccessible since it won't have any files in place to handle requests.
So the next step is to unpack the Drupal 6 files and folders and put them into your installation directory.
Re-Configure Your Installation
Copy your backed up "files" and "sites" directories to the Drupal
installation directory. If other system files such as .htaccess or
robots.txt were customized, re-create the modifications in the new
versions of the files using the backups taken in step #1.
Please note that by restoring your 'sites' folder you will also be restoring the 'modules' folder(s) contained within it. Since this is coming from your backup, those modules folder(s) will contain modules for Drupal 5.x. Therefore, it is a good idea to empty out the modules folder(s) you have under the sites folder before moving onto the next steps. This will reduce the likelihood that you accidentally leave and old Drupal 5.x version of a module in place and forget to replace it with its Drupal 6.x version. Or worse, by leaving the folders in place, you may accidentally merge the contents of the Drupal 6.x version of a module folder with the old Drupal 5.x version.
You now run update.php by going to http:// yourdomain/update.php and follow the instructions. This script does the work of upgrading the Database preparing it for use with Drupal 6.x. Note, that you are doing this immediately after you have upgraded the Drupal core installation files and folders but BEFORE you have replaced/upgraded any contributed or custom module folders.
Upgrade Contributed Modules
In the planning stage you made a list of modules and did some research on their upgrade path. You made sure that there were Drupal 6 versions of those modules and if not you researched some alternatives you may have to use instead. You also made note of any special upgrade requirements for your modules. By getting Drupal 5 upgrade ready you updated your contributed modules so they could follow the proper upgrade path. You also downloaded all the Drupal 6.x version of those modules (along with any new dependencies they may have).
Now, following your module checklist, install each of your contributed modules. In most cases you do this as you normally would with a fresh install of Drupal. Place the folders in the sites/all/modules folder and go to Administer » Site Building » Modules and re-enable the modules. But, some modules may have special instructions. For example CCK has a specific upgrade instructions for moving from Drupal 5 to Drupal 6. Make sure to follow those upgrade instructions carefully.
After you've got your modules in place and re-enabled you will have to run update.php again by going to http:// yourdomain/update.php. This time it will upgrade the database tables used by your modules.
Re-enable the Drupal 6.x version of your theme
If you had a custom theme, in getting Drupal 5 upgrade ready you migrated that theme to Drupal 6. Otherwise you downloaded a Drupal 6.x compatible theme. In either case you can now enable it.
Testing and Finishing Up
With all that done, your site is now technically 'upgraded'. But, before you declare success and go off to upgrade your live site, you will want to look into a few things.
Did you miss anything? Is there anything on your planning document that you forgot to do? Did you remember to enable every sub-module?
Did your data survive the upgrade? Is published content still published? Are comments still being displayed?
Are your menus intact?
Have you checked the permissions page? Have modules introduced new permissions or taken old ones away? Do these changes impact your site?
Can you create new content error free? Have you tried to create content with all your different content types?
Did your theme migration work perfectly? Were there some parts of the theme you couldn't test until you completed the upgrade?
What else can you think to test?
In the end, you know your site better than anyone and you know what things you will want to test to ensure that everything still works. Only you will know if your upgrade was a success.
Once again, please feel free to leave comments along with your own suggestions or links that may be helpful to others. I covered a lot of ground in the past few posts, but I certainly may have missed some things along with way. I'll be sure to update these docs with information from your comments.
- Links from the previous post on this topic
- Custom Module Conversion Guide
- Custom Theme
- Drupal.org Upgrade Documentation (much like UPDATE.txt but with additional notes and user comments)
- Optional upgrade configuration steps to plan for (a good companion to this post)
- Drupal 6 Upgrade Screencast
- Freemind Mind Mapping Software (I find it useful for documenting plans and TODO lists)
- Getting Started Guide for Acquia Drupal (Commercial Distribution of Drupal) See Chapter 7
- The Update Status Module project page on Drupal.org
- The Upgrade Status Module project page