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:

  • high efforts and time consumption to adapt the patch

  • long duration for performing the patch

  • high working effort for testing the patch

Disadvantages during patch creation process:

  • high working effort when creating and testing the patch package

  • high optimization effort

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:

  • flexible patch process - dynamic handling of adjustments and errors

  • parallel processing - single process steps can be executed in parallel

  • revision security - current changes don’t influence older versions

  • central information interface - providing information about patch and system

  • unified logging - central repository of all patch-relevant messages

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.

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.

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/

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:

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.