*/
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.

Project
File
Function
Change
Event
basicevent.module
basicevent_menu
Delete function as it only contains a "node/add/event" entry and this is automatically handled by Menu API as indicated in TODO comment.

event.theme
event_theme
Uncomment this hook_theme stub function as indicated in TODO comment.

Various
Manually fix the parameters on the l() functions by adding "array('atrributes' =>" in front of existing "array" as indicated in TODO comment.

event.module
event_menu
Create the event_init routine and move the drupal_add_css line to it.

event_menu
For the entry "admin/settings/event" which uses a page callback of "system_admin_menu_block_page" add two lines: 'file' => 'system.admin.inc' and 'file path' => drupal_get_path('module', 'system').

event_nodeapi
Add "include_once(EVENT_PATH .'/event_timezones.inc');" Not sure why this wasn't required by 5.x.
Fivestar
fivestar_color.inc
fivestar_color_theme
Copy theme registry entry for fivestar_color_form to hook_theme in module file.

fivestar.module
fivestar_theme
Uncomment this hook_theme stub function and copy fivestar_color_form entry from fivestar_color.inc as indicated in TODO comment.

fivestar_menu
Comment out "if ($may_cache)" block begin and end lines that no longer apply as indicated in TODO comment.

fivestar_form_alter
Revise parameters in call to fivestar_comment_form_alter to be ($form, $form_state, $form_id).

fivestar_nodeapi
Replace "$node->in_preview == FALSE" with "$node->build_mode != NODE_BUILD_PREVIEW" as in_preview is no longer valid.

fivestar_forms
Reduce indexes of "$args[n]" by one due to addition of $form_id to function signature. Example: replace "$args[1]" with "$args[0]".

fivestar_custom_widget
Comment out "#base" element and add "$form['#submit'][] = 'fivestar_form_submit';" as indicated in TODO comment at top of file.
VotingAPI
/votingapi.module
votingapi_menu
Comment out "if ($may_cache)" block begin and end lines that no longer apply.
Signup
signup.theme
signup_theme
Uncomment this hook_theme stub function as indicated in TODO comment.

signup.module
Various
Replace code calling db_num_rows as it has been removed from the API.

Various
Manually fix the parameters on the l() functions by adding "array('atrributes' =>" in front of existing "array" as indicated in TODO comment.

signup_forms
Comment out 3 lines with "$args[n]" at beginning of function as indicated in TODO comment.
Scope: Planet DrupalTags: developmentmodule conversionautomation