Introduction

Patcher Module is created as an extra module to apply code changes or fixes in between releases. This is a module for administrator. It connects to update.atutor.ca automatically, finds the available patches for the installed ATutor version, and displays all the available patches to allow administrators to install.

Patch directory structure at update.atutor.ca

http://update.atutor.ca
  |_
      patch
        |_
           1_6
             |_
                  patch_list.xml
                  1_6-1
                      |_
                          patch.xml
                          [new files to add, .php files have to be rename as .new file]
                          [files to overwrite, .php files have to be rename as .new file]
                  1_6-2
                      |_
                          patch.xml
                          [new files to add, .php files have to be rename as .new file]
                          [files to overwrite, .php files have to be rename as .new file]

Each ATutor version has a folder under "patch" folder. In version folder, patch_list.xml contains general information of all patches that are available for this version. One of the elements <patch_folder> in patch_list.xml specifies the name of the subfolder where all the details for the patch are located.

Naming conventions:

1_6: version folder for ATutor version 1.6, as so, 1_6_1 is for version 1.6.1 

1_6-1: patch folder for ATutor 1.6 and patch sequence number 1. As so, 1_6-2 is for ATutor 1.6 with patch sequence 2. Please note that this naming convention is not mandatory as the script uses the name specified in patch_list.xml, element <patch_folder>.

.new files: all .php files have to be rename to .new when being placed into patch folder, for example, login.php needs to be renamed to login.new. It's because PHP is installed in server where update.atutor.ca is located, when Patcher module fetch a .php file from update.atutor.ca, the file is parsed as a php script and only the output of execution of php script is returned. This is not we want, we want to have a straight text file.

Note: 

1. Patches are forced to be applied in the order of sequence to avoid conflicts.

Patch_list.xml

Patch_list.xml is in version folder and contains summary information of all the patches that are available for this version When a new patch is available, related information has to be added into this file.

Important element:

<available_to>: values can be public or specific user; when public, available to all users

Sample patch_list.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<patch_list>

            <patch>
                        <atutor_patch_id>00001</applied_version>
                        <applied_version>1.6</applied_version>
                        <sequence>1</sequence>
                        <patch_folder>1-6_1</patch_folder>
                        <description>Patch No. 1 for ATutor 1.6</description>
                        <available_to>public</available_to>
            </patch>

           <patch>
                        <atutor_patch_id>00002</applied_version>
                        <applied_version>1.6</applied_version>
                        <sequence>2</sequence>
                        <patch_folder>1-6_2</patch_folder>
                        <description>Patch No. 2 for ATutor 1.6</description>
                        <available_to>Royal Danish Defence College</available_to>
            </patch>

</patch_list>

Patch Files in sub-patch folder

The files in patch folder, for example 1-6_1, are:

1. patch.xml
2. the new files to be copied into ATutor.
3. the modified files to overwrite the old ones in ATutor

Patch.xml

patch.xml is the most important file to apply patch, example attached in the next section. patch.xml describes all the changes on database and code. Includes:

1.      all database operations

2.      copy new file

3.      delete old file

4.      overwrite old file 

5.      modify file content: includes delete, replace

Important element tags:

<sql>: holds all SQL statements.

<files>: holds all actions on scripts and files. <file> is the sub-element in <files> that holds all modifications on scripts and files. Its important sub-elements:

      <action>: alter, add, delete, overwrite

      <action_detail>: has to provide when <action> is "alter". <type> can be delete, replace

Sample patch.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<patch>
             <atutor_patch_id>00001</applied_version>
            <applied_version>1.6</applied_version>
            <sequence>1</sequence>
            <description>Sample patch XML</description>

            <sql>
                        ALTER TABLE `tests` ADD `description` TEXT NOT NULL AFTER `title`;
            </sql>            

            <files>
                        <file>
                                    <action>alter</action>
                                    <name>create_test.php</name>
                                    <location>tools/tests/</location>
                                    <action_detail>
                                                <action>delete</action>
                                                <code_from></code_from>

                                                <action>replace</action>
                                                <code_from></code_from>
                                                <code_to></code_to>
                                    </action_detail>

                        </file>

                        <file>
                                    <action>add</action>
                                    <name>calendar.gif</name>
                                    <location>docs/images/</location>
                        </file>

                        <file>
                                    <action>delete</action>
                                    <name>results_all_csv.php</name>
                                    <location>tools/tests/</location>
                        </file>

                        <file>
                                    <action>overwrite</action>
                                    <name>results_all.php</name>
                                    <location>tools/tests/</location>
                        </file>
            </files>
</patch>

Note:

Some characters have a special meaning in XML.

If you place a character like "<" inside an XML element, it will generate an error because the parser interprets it as the start of a new element.To avoid this error, replace the "<" character with an entity reference "<". There are 5 predefined entity references in XML:

New Tables

3 new tables are required to keep track of patches that have been applied to current version of ATutor. They are:

patches

For general patch information. 

patches_files 

To keep track of all the files that are altered, added, deleted, overwritten for each patch.

patches_files_actions

To keep track of all actions that are done on files in patches_files

Module Workflow

1. connects to update.atutor.ca, read patch_list.xml to get and list all available patches for installed ATutor version
2. Only the radio box of the patch with lowest sequence number is enabled. Once this patch is installed, the radio box is disabled and the radio box of the patch with the next lowest sequence number is enabled
3. installation

        (1)   Locate "patch.xml" in the sub-patch folder specified in patch_list.xml
        (2)   Execute SQL
        (3)   If file action is "alter":
                * check if the file and folder is writable, if not, display message "make writable". Folder has to be writable is because of creating backup file
                * compare local copy with SVN, if the local copy is different, check table patches see if it's modified by previous patch installation.
                   If it's not modified by patch, ask user if they want to proceed. If they do, backup and alter the local file
               If file action is "copy"
                * check if the folder is writable, if not, display message "make writable".
               If file action is "delete"
                * check if the file is writable, if not, display message "make writable".
                * backup and delete the local file
               If file action is "overwrite"
                * check if the file is writable, if not, display message "make writable".
                * Use the way described in "alter" action to decide if the local file is modified by user.
                   If it's modified, ask user if they want to proceed.
                   If they do, copy the new patch file to local with patch suffix and alert user to merge changes manually
        (4)   Run <action_detail>: delete, replace
        (5)   Loop through step (3), (4) for all files, when finish, the patch is installed as database and file changes are done
        (6)   alert user to make unwritable for all the files/folders that are given write permission at step (3).

All informations about "files/folders to remove write permission", "backup files", "patch files" are kept in table patches. Users can retrieve these info any time by clicking button "View Message".