Automated module conversion

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.

Comments

Excellent Work!

Thanks for the write-up and for your work on the module! I think that Deadwood is definitely the kind of tool that module developers need. Combined with Coder, I think it can increase both the speed with which modules are updated to the latest core release and encourage continued improvement in the quality of those modules. This write-up has removed my skepticism and I'm now eager to try the tool for myself!

~t-dub

http://chicagotech.org

any new module out there

I'm seeking a updated module of a 5x version for deleting item menus that are no longer needed. Needed for Version 6x.

a error

Hi
I have a error to convert http://drupal.org/project/toplist modules to drupal 6
here is this error : Parse error: syntax error, unexpected ',', expecting ']' in G:\xampp\htdocs\6\sites\all\modules\toplist\toplist.module on line 174

I ran my module through the

I ran my module through the automatic converter, activated it and now I have a beautiful white page without anything.It was just a testing environment (of course), but I hoped it can safe me some time converting the modules.
Nevertheless, nice work.
XPectIT