Last updated February 20, 2010. Created on February 12, 2010.
Edited by solotandem. Log in to edit this page.

As part of the Drupal core workflow, to write an upgrade routine:

  • Download and install the Coder module and its submodules, including Coder Upgrade.
  • Copy (or symbolically link) the /coder/coder_upgrade/tests/old/samples directory to your local files directory, by default at files/coder_upgrade/old/samples.
  • Check out an upgrade to work on by assigning the upgrade issue to yourself.
  • Write an example function in the example.module file (see Step 2) to test your routine. For a change to an API hook, the function needs to be named "example_" followed by the hook name. By convention, for other changes, the function should be named "example_" followed by the anchor tag on the issue page. For example, if you were working on Update functions in .install files must include a Doxygen style comment (hover over the link and look at the text following the "#" symbol), your function would be named "example_update_php."
  • Include two to three code samples in the example function. For example, an upgrade routine may need to change a function call. This call may be: 1) a standalone expression, 2) part of a conditional expression (e.g. if (function_call()), 3) in the body of a case statement, or 4) any number of other places. The usefulness of the upgrade routine correlates with the number of code samples it is tested with.
  • Write the expected example function after upgrade in the example.module file in /coder/coder_upgrade/tests/new/samples directory.
  • Write the conversion routine(s) in Coder Upgrade. To upgrade an API hook, add an alter hook to coder_upgrade.function.inc with the name "coder_upgrade_upgrade_hook_HOOK_NAME_alter." To upgrade a function call, add an alter hook to coder_upgrade.call.inc with the name "coder_upgrade_upgrade_call_FUNCTION_NAME_alter." Refer to coder_upgrade.api.php for documentation of the hooks provided by the module.
  • Test the upgrade routine by running Coder Upgrade and comparing the output file saved by default in the files/coder_upgrade/new/samples directory to the expected output file created earlier.
  • Post the upgrade routine code and example function as attachments to your comment on the issue. (A patch file works too.)

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.