PatchFoswikiContrib

Apply critical patches to Foswiki.

Usage

This extension allows you to "hotfix" urgent issues on your Foswiki system. It has been tested on Foswiki 1.1.0 and beyond. It does not work on Foswiki 1.0.x.

When this extension is installed, it adds some required libraries to your Foswiki system, and includes a plugin to display an inventory of patches on the system. This extension does not ship with any patches. this extension will be identified as a dependency of the actual patch, so that necessary infrastructure is installed.

Patches are only applied if the target file is an exact match to the original file. There is no attempt to do "fuzzy" patching.

There is no "dependency" between patches. Patches are installed in order of their patch file name.

Patches will be mapped from the default Foswiki filename to the directory location used on the target system.

Before any file is patched, a backup is copied to working/configure/backup/<Itemxxxx-nnn-YYYMMDD-HHMMSS>. If archive tools are found on the system, a zip or tar archive is created of the backup.

Warning: Can't find topic Extensions.PatchFoswikiContribPlugin

Building a patch

A separate version of a patch extension has to be built for each patch. The only patches installed are those identified in the manifest of the Extension. This extension adds some infrastructure that a future Foswiki could use to apply patches from configure.

Format of a patch file

The format of the patch file is a collection of related patches, one for each version of a target file. The patch file consists of

Summary

A general description of the patch. It can be any number of lines long and will be reported in the installation log.

Patch Target

A single line used to specify exactly which file is to be patched. Identifies a single version of a patch along with the md5 of the target file, the filename and a comment.

~~~PATCH fdeeb7f236608b7792ad0845bf2279f9:76e28354522a6d6cccc76c66f99d2424  lib/Foswiki/Configure/Dependency.pm (Foswiki-1.1.8,Foswiki-1.1.9)

• ~~~PATCH Identifies this as a patch
• fdee..79f9 is the 32 character MD5 hash of the original version of the unpatched target file. If this matches the file, the patch is eligible to be installed.
• 76e2..2424 is the 32 character MD5 hash of the patched version of the file. If tthis matches the file, the patch is already applied and could be removed.
• lib/Foswiki... The target file name
• (Foswiki-1.1.8,Foswiki-1.1.9) A comma separated list of releases that this patch covers.

The patch

A patch in unified diff format, such as: diff -Naur oldversionFile newVersionFile

Creating the patch file,

• For the "current release":
  • Calculate checksum of original released file: md5sum lib/Foswiki/Target/File.pm >> Itemxxxx-xxx.patch
  • Get a starting point from the fixing git patch: git show [hash] lib/Foswiki/Target/File.pm >> Itemxxxx-xxx.patch
  • Verify that this diff can be applied to the "released" version of the file
  • Edit the patch file buiding the ~~~PATCH record and remove the md5sum record

This extension will processes all patches from a single file, or a patch can be build as separate patch files. If a site might be required to manually apply patches (for ex. the web interface is broken), separate files will be more compatible with the patch utility.

• For each additional release that the patch will cover:
  • Calculate checksum of original file: md5sum lib/Foswiki/Target/File.pm >> Itemxxxx-xxx.patch
    • If this is identical to another revision, you are done, move to the next version.
  • Copy the target: cp lib/Foswiki/Target/File.pm lib/Foswiki/Target/File.pm.new
  • Manually patch the new file
  • Calculate the diff: diff -Naur lib/Foswiki/Target/File.pm lib/Foswiki/Target/File.pm.new >> Itemxxxx-xxx.patch
  • Edit the patch file to build the ~~~PATCH record and remove the md5sum record.

Installation

Patches are applied during the POSTINSTALL exit, and removed in the PREUNINSTALL exit. You must install this extension using the "Extension Installer" to get automatic patching. If this extension is installed by direct unzip / tar -x, or using pseudo_install.pl, patches will not be applied and will have to be manually patched using the patch tool.

Manual installation

unzip or tar -x the extension archive. It can be extracted into the root of the foswiki installation if the directory paths use the default location. The structure of a typical patch:

|-- data
|    |-- System
|          |-- PatchItem12345Contrib.txt
|
|-- lib
|    |-- Foswiki
|           |-- Contrib
|                  |-- PatchItem12345Contrib.pm
|                  |-- PatchItem12345Contrib
|                         |-- DEPENDENCIES
|                         |-- POSTINSTALL              (Executed by installer to apply the patches)
|                         |-- PREUNINSTALL             (Executed by installer to removes the patches)
|-- working
     |-- configure
            |-- patch
                  |-- Item54321-001.patch
                  |-- Item54321-002.patch
                  |-- Item12345-001.patch
                  |-- Item12345-002.patch
                  |-- Item12345-003.patch

The files in the working/configure/patch directory are the actual patches. If a collection of related files is patched in a single file, they can be manually applied by changing to the root of the install and running:

patch -p0 < working/configure/patch/Item54321-001.patch

By a "collection of related files", Item12345-001.patch might contain patches for lib/Foswiki.pm and lib/Foswiki/Render.pm. These could be appplied directly. But if Item12345-002.patch contained different versions of patches for the same file, ex. lib/Foswiki.pm for 1.1.9, and lib/Foswiki.pm for 1.1.8, then the file would have to be split apart in order to apply it manually.

Info

Dependencies:	Name Version Description Algorithm::Diff >=0 May be required for lib/CPAN/lib/Text/Diff.pm Carp >=0 May be required for lib/CPAN/lib/Text/Diff.pm, lib/CPAN/lib/Text/Diff/Table.pm, lib/CPAN/lib/Text/Patch.pm Exporter >=0 May be required for lib/CPAN/lib/Text/Diff.pm, lib/CPAN/lib/Text/Patch.pm File::Copy >=0 May be required for lib/Foswiki/Configure/PatchFile.pm File::Path >=0 May be required for lib/Foswiki/Configure/PatchFile.pm File::Spec >=0 May be required for lib/Foswiki/Configure/PatchFile.pm Foswiki::Time >=0 May be required for lib/Foswiki/Configure/PatchFile.pm
Change History:
2.1 (15 Nov 2015)	Foswikitask:Item13759: Restructure to support internal changes in Foswiki 2.0. Update to latest CPAN libs.
2.0 (22 Apr 2014)	Foswikitask:Item12863: Restructure PatchFoswikiContrib to remove obsolete patches originally shipped with the extension.
1.5 (26 Dec 2012)	Foswikitask:Item12312: Add reporting of patch status, Foswikitask:Item12314: Add feature to reverse a patch. Note that there are no changes to the patches shipped in this version.
1.4 (14 Dec 2012)	Some perl complains about exporting of function names.
1.3 (28 Nov 2012)	Rework to support multiple patch installation. Rename to PatchFoswikiContrib from PatchItem12225Contrib. Add a 2nd patch file.
1.2 (15 Nov 2012)	Manifest errors. Configure was complaining about non-writable working files.
1.1 (15 Nov 2012)	Don't include / when matching filenam, causes undefined variables on Windows.
1.0 (09 Nov 2012)	Initial version