Switch the patch process to new patch API 6.17.41
Created: 6.14.0; Updated: 6.17.5

The previous ePages patch process was a combination of Perl scripts and a 'makefile'. Due to the static process manual adaptions are inevitable for each version. One consequence of such unflexible process was a high error rate especially for highly customized systems.

Other disadvantages for patching customized systems:

Disadvantages during patch creation process:

To come around the disadvantages the patch process will be converted step by step into a Perl API variant beginning with version 6.13.3. It is planned to have the process changes completed with version 6.15.

The following goals will be achieved:

Table of Contents

1 Concept

A single API module (patch handler) is created per patch process step. The API modules replace the Perl scripts and the numerous system commands from the Makefile.

Special patch steps can be controlled by entries in a file named "Config". This file is loaded into the SQLite database when starting the patch process. Afterwards the data are available for all patch API objects.

Patch API modules are started from a "makefile" defining the order of all patch steps.

Patch process steps can be skipped completely by a corresponding entry in file "Conf/SkipHandler". See chapter "Changes in the patch folder structure"

All relevant data are provided by an information interface. The objects of the corresponding interface module use a SQLite database holding all required patch information.

Each patch handler will provide a single patch function per version. A new patch function will be created for related changes in a new version. This allows a less version dependent patch process. The version specific patch function will be called for each version to be patched. Using the patch functions of several versions facilitates multiple consecutive patches to be combined with less effort.

In addition the new approach allows performing special patch process steps simultaneously. The target is to patch several stores that way at the same time.

Using the patch API, the information interface and the integration of the CartridgeInstaller objects allow unified logging. The log messages of different levels are written in separate log files. Messages with high importance can be checked quite easily since each patch process step writes its own log file. For more information see chapter "Logging".

In a later version the patch tool will be extended by a statistics based estimation to forecast the duration of the patch process.

2 Changes in patch folder structure

New folders in patch folder:

- /API

  Patch handler modules (PatchPrepareHandler, ...)

- /Conf

  Configuration files to adjust single patch process steps
 
  - config
    
    The entries determine how single patch process steps are executed
    Example:
      ...
      #If "1", the cartridges.xml is patched; if "0" the cartridges.xml won't be changed
      PatchCartridgesXML=1
      ...
    
  - SkipHandler
    
    The entries determine which handlers are skipped from patch process
    
  - TargetVersion
    
    Contains the target version of the patch.
    The entry must not be changed manually.
    
  - Versions
    
    List of all supported versions in order of release.
    The list must not be changed.

- /Data

  
  - Patchreport.html
    
    This HTML file displays the status of the patch process. It is re-created according to the patch process and updated in 
    the browser every three seconds. 
    
  - PatchSystemInfo.db 
      
    This database is the basis of the information interface. It contains all relevant patch and system information.
    This file must not be changed or deleted manually.

- /Database

  SQL-files with all necessary tables created in the PatchSystemIfo.db

- /t

  Test cases to check the basic functions of the information interface
  These test cases should always provide a positive result. They can be ignored when applying the patch.
  All tests use a separate and temporary test database which does not affect the normal patch process.

3 Logging

Log files exist in different levels of importance, one file for each level. Each file contains messages of the according log level only. The file with the lowest level contains all log messages.

  Level 0 - most important entries
  ..
  Level n - all log entries

Level 0 is a subset of Level n.

For each handler a separate log file is created. It contains all log messages related to this handler. This file is also a subset of Level n.

The log files are located in:

  $EPAGES_SHARED/Patches/var-patch_[version]/logs/[hostname]/
  Example:
  $EPAGES_SHARED/Patches/var-patch_6_13_3/logs/qa-vm-win2k8R2-1/

4 Notes for application

- Use of own Cartridges.xml

  In the file "Config" you can determine if the patch can change the existing Cartridges.xml. 
  In addition you can provide a Cartridges.xml for each version which is used as soon as the relevant patch is performed.
  The version bound Cartridges.xml has to be copied into subfolder /Config.
  The following naming conventions must be observed:
  
    Cartridges_[version_number_using_underscores].xml
    
    Example: Cartridges_6_13_3.xml
  The patch process uses the files automatically if they are available in /Config.
  
  Example:
    If you want to use own customized Cartridges.xml files for patches 6.13.2 and 6.13.3 you have to copy the files into 
    folder /Config:
  
      /Config
    
        Cartridges_6_13_2.xml
        Cartridges_6_13_3.xml
      
  Using a customized Cartridges.xml with automatic patching of Cartridges.xml disabled requires to edit the file manually 
  to add new cartridges and to delete obsolete cartridges. To keep an outdated Cartridges.xml may lead to errors during 
  the patch or while the system is running after the patch.

- Patch restart

  
  It is possible to put the patch back into the initial state to restart it again.
  Therefore the target "reinitialize" is now available:
  
    perl patch.pl reinitialize
  All information being required for the patch are initialized again or set back to the initial state.
  
  To reset the patch back to the initial state execute the following commands (example):
  
    perl patch.pl reinitialize 
    perl patch.pl prepare
  
  A restart of the patch is only recommended after steps "Prepare" and "Preinstall". Once database changes have been made 
  in step "Install" (e. g. foreign keys added) errors can occur and the restarted patch process may abort.


Copyright ePages GmbH 2016