Operating the Patch Automated Reintegration Tool

The Patch Reintegration Tool is located in directory

<moodleroot>/report/patches/__command_line_tool/patch_reintegrator

It might be a good idea to keep it in development instance on your own computer, and remove it from production servers.

Step 0: Preliminary Patch Markup

All patchs that need to be identified should be marked from start to end. The default markup is identical to the patterns used by the Patch Report :

Patch start : // PATCH : Some reason Patch end : // /PATCH

Patch comments should be alone on their code line:

avoid having this

  foreach($loops as $loop){ // PATCH : starting change here
    ....
  }

but integrate loop start in patch section like this:

  // PATCH : starting change here
  foreach($loops as $loop){ 
    ....
  }

Some config keys define the sart and end pattern of the detector:

  //start pattern consider a full line patch mark pattern 
  $CFG->patchstartpattern = "\\s*\/\/\/?\\s*PATCH [^\\n]*\\n+";

  //end pattern consider a full line patch mark pattern 
  $CFG->patchendpattern = "\\n*\\s*\/\/\/?\\s*\/PATCH\\s*";

You might change the patterns to cope with your marking syntax.

Step 1: Setting up code bases

The first step is to setup copies ready for processing in the right place. the default tool configuration uses the "test" subdirectory with three subvolumes :

customized : is the location where your actual moodle code should come.
target : is the location where the upgraded standard download of Moodle should be dropped
merged : will be the location where the mix of both will be produced. You shall let it empty.

Note 1: drop the top level of Moodle in those dirs, that is, config.php will be in "customized" or "target". Note 2: some options of the configuration file allow to patch directly the source version (customized). This setting is rather for patching directly the moodle "in place". It is not recommended as experience shows that the probablility of having unresolved patch relocation is about 10% for a jump of several minor releases (f.e. jumping from 1.9.7 to 1.9.18, or 2.3.0 to 2.3.4).

Step 2: Processing

Run the processor by invoking the main.php script from CLI command line:

   >php main.php

You may obtain command line syntax for options asking for help:

  >php main.php -h

Step 3 : Getting result and checking unresolved patchs

Once processed, a file called :

  patch.log

is generated in the root of the merged codebase.

If this does not happen, check the tool's configuration.

The patch.log file summaries all patch operations and particularily reintegration issues.

These are known cases of reintegration failures:

patch neighbourhood has light or severe changes
destination file does not exist any more
there are two consequent patchs that are too close in code : the second one collides with the post-detecton pattern.
a patch gets too close from file start an end boundaries

Get each failure report and reintroduce the change manually, after checking it is still needed for your purpose.

Here comes a failure sample:

And what happened there:

Step 4 : Getting missing stuff

The patch reintegrator do check some known locations for non standard additions, in order to get them back in the merged version. Usually all kind of plugins will be recovered.

One special place is /lib.

/lib is not likely to be changed or added non standard libraries. Thus if some extra developements havve asked to move some additional libraries there, they will NOT be recovered and you have to copy them by your own.

From Moodle 2.0 and upper, new contrib rules try to discourage bringing extra libraries to /lib. In place, it will be promoted to build a 'local' plugin where a contributor can put his extra framework libs together.

Step 5 : Get merged code base to the original execution location

You (of course) have made a prior backup of the source, database and moodledata file container.

Now you can update all data and check the stability of your upgraded customization.

Documentation