Writing an upgrade routine: Introduction

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