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.)