Drupal Planet

Case Study: Automated module conversion from 5.x to 6.x using Deadwood

As the creator of the Deadwood project, I (solotandem) prepared this case study in conjunction with the 1.2 release. This post describes my experience using Deadwood (6.x-1.2) to convert four 5.x projects to the 6.x API. The four projects are: Event, Fivestar, Voting API, and Signup. Before anyone replies with a, "Hey, don't you know these projects have already been ported to 6.x?," let me confirm that I am aware of this. These projects were selected because the 5.x versions had been used in a recently completed site (developed after the Drupal 6 release) before the 6.x versions arrived.

The purpose of the Deadwood project is to automate as much as possible the task of updating a contributed project for Drupal API changes, and thereby simplify the task of porting contributed projects shortly after a new Drupal release. As Drupal matures and becomes more widely used, I believe we can further encourage its use if updated projects are released concurrent with the Drupal core releases. (I suspect we all like it when Firefox 3 comes out and most of the plugins are available the same day or within a couple weeks. To me, that speaks volumes about a project.)

My plan is to update Deadwood for the 7.x API during the upcoming code freeze so that developers will have ample time to prepare and test a 7.x release of their projects.

A few developers have indicated their resistance to using an automated conversion tool. The remarks tend to sound like, "I wouldn't want a program to update my module." To which I wonder why they use computers at all, since automation seems to be what the machines tend to be good at. As for me, I am quite happy to have "some program" make 90-95% of the mundane changes for me so I can focus my attention on more interesting tasks. Deadwood is not to be used blindly nor does it make all the necessary conversions. As stated in the instructions to the module, we strongly recommend you use a file or directory comparison utility to review the changes made to the project files.

Conversions made by Deadwood include:

• Updates the project .info file.
• In the .install file, creates a hook_schema function and modifies the hook_install and hook_uninstall functions in accordance with the new Schema API.
• Modifies the hook_menu function for Menu API changes.
• Updates the code for many of the Forms API changes.
• Creates the theme registry entries in a hook_theme function.
• Adds "TODO" comments to the files indicating changes to be made manually as well as new features of the Drupal APIs that may be useful.

Converting a project

In three easy steps:

• Download and install the Deadwood module to your Drupal 6.x development site.
• Copy your project directory to the module input directory (by default, sites/default/files/deadwood).
• On the conversions build page (admin/build/deadwood), click the "Convert files" button after you select the file types to convert and the project directory.

For those who like more details, some optional steps are:

• Visit the help page (admin/help/deadwood) to read detailed instructions on using the module.
• Visit the settings page (admin/settings/deadwood) to specify the name of the directories where files will be read from and written to (the defaults are deadwood in and goodwood out) (Note: a proper jingle would be "out with the deadwood, in with the goodwood.")
• Visit the API settings page (admin/settings/deadwood/api) to specify the default conversions to be applied to your project.

Reviewing the changes

Review the changes using your favorite "diff" utility. Note the "TODO" remarks and make any necessary changes. Look for other changes to make by reading the conversion roadmaps and noting the items not addressed by Deadwood (see the API changes settings page mentioned above). Try out the module and correct any run-time errors.

Install the Schema module to see if the Deadwood-generated schema is consistent with the tables installed. This module will also generate code that can be put back in the hook_schema function. You could also use this module to generate the schema code, but Deadwood offers a "one-stop" upgrade service.

Changes required to make modules work in 6.x

The following table indicates the manual changes needed to make the four projects work in 6.x after converting them with Deadwood. Please note that many of the manual changes are indicated in the "TODO" comments.