PatchFoswikiContrib < System

You are here: BACCHUS Wiki>System Web>PatchFoswikiContrib (revision 1) (raw view)
<!--
One line description, required for extensions repository catalog.
   * Set SHORTDESCRIPTION = File patch tool for Foswiki
-->
---+!! PatchFoswikiContrib

%SHORTDESCRIPTION%

%TOC%

---++ 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.

When this extension is installed, it adds some required libraries to your Foswiki system, and then in the Post-installation exit, applies any patch files found in the manifest.  This extension ships with a hotfix for the following items:

| *Original Issue* | *Patch File* | *Description* |
| [[http://foswiki.org/Tasks/Item12225][Item12225]] | =Item11267-001= | Extensions released with new style Perl version strings prevents installation of any further extensions. |
| [[http://foswiki.org/Tasks/Item11267][Item11267]] | =Item11267-002= | Extensions are re-installed because of dependency on svn Revision levels. |

Patches are only applied if the target file is an _exact_ match to the original file.  There is no attempt to do "fuzzy" patching.   Note however that a patch can be built to cover multiple versions of the file.

There is no "dependency" between patches.  Patches are installed in order of their patch file name.  In the above patch list, =Item11267-001.patch= makes unrelated changes to the file patched in =Item11267-002.patch=, but __must__ be installed first so that the patch signatures match.

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/&lt;Itemxxxx-nnn-YYYMMDD-HHMMSS&gt;=.  If archive tools are found on the system, a zip or tar archive is created of the backup.

---++ Patch files found on this system

This report lists the patch files found in the =working/configure/patch=
directory.  The patch summary is displayed, followed by a list of each
candidate patch.  The *Status* column is set to:
   * *N/A*: This version of the patch does not apply to this file. The file might have been subsequently modified by another patch or by manual edit.
   * *PATCHED*: The patch appears to have been applied, and no other modifications have been made to the file.
   * *APPLIES*: The patch matches and is eligible to be applied.

%PATCHREPORT%

---++ Building a patch

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

---+++ Create 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 =~~~PATCH fdeeb7f236608b7792ad0845bf2279f9:76e28354522a6d6cccc76c66f99d2424  lib/Foswiki/Configure/Dependency.pm (Foswiki 1.1.5)=:  Identifies a single version of a patch along with the md5 of the target file, the filename and a comment.
      * =~~~PATCH= Identifies this as a patch
      * =fdee..79f9= is the MD5 hash of the original version of the unpatched target file.
      * =fdee..2424= is the MD5 hash of the patched version of the file.
      * =lib/Foswiki...= The target file name
      * =(Comment)= A comment in optional parenthesis, such as the foswiki version that shipped this file..
   $ The patch:  A patch in unified diff format =diff -Naur oldversionFile newVersionFile

To build a 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

   * 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.

Here is an example patch file for the Foswiki 1.1.5 and Foswiki 1.l.4 versions of the files. (EXTENSIONS.pm was not modified between 1.1.4 and 1.1.5):
<verbatim>
Author: GeorgeClark <GeorgeClark@0b4bb1d4-4e5a-0410-9cc4-b2b747904278>
Date:   Mon Nov 5 05:07:25 2012 +0000

    Item12225: Don't use "HEAD" to detect pseudo install.

    A real, non-pseudo-installed extension will crash configure if a
    perl version object is compared to an alpha string.

    9999.99_999 will be used to indicate a pseudo-installed release.

    git-svn-id: http://svn.foswiki.org/trunk@15909 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

~~~PATCH fdeeb7f236608b7792ad0845bf2279f9  lib/Foswiki/Configure/Dependency.pm (Foswiki 1.1.5)
--- lib/Foswiki/Configure/Dependency.pm 2012-11-07 23:46:56.378148979 -0500
+++ lib/Foswiki/Configure/Dependency.pm.new     2012-11-07 23:46:14.091649218 -0500
@@ -220,7 +220,7 @@
             if ( -l "$dir/$path" ) {

                 # Assume pseudo-installed
-                $this->{installedVersion} = 'HEAD';
+                $this->{installedVersion} = '9999.99_999';
             }
             last;
         }

~~~PATCH 76e28354522a6d6cccc76c66f99d2424 lib/Foswiki/Configure/UIs/EXTENSIONS.pm (Foswiki 1.1.0-1.1.5)
--- lib/Foswiki/Configure/UIs/EXTENSIONS.pm     2012-11-07 23:45:21.269274066 -0500
+++ lib/Foswiki/Configure/UIs/EXTENSIONS.pm.new 2012-11-07 23:46:39.844344573 -0500
@@ -280,7 +280,7 @@
         if ( $ext->{installedRelease} ) {

             # The module is installed; check the version
-            if ( $ext->{installedVersion} eq 'HEAD' ) {
+            if ( $ext->{installedVersion} eq '9999.99_999' ) {

                 # pseudo-installed
                 $install = 'pseudo-installed';

~~~PATCH 4e525d29a245785ae810316835c18e62 lib/Foswiki/Configure/Dependency.pm (Foswiki-1.1.4)
--- lib/Foswiki/Configure/Dependency.pm 2011-12-20 10:33:22.000000000 -0500
+++ lib/Foswiki/Configure/Dependency.pm 2012-11-08 17:05:55.982213647 -0500
@@ -220,7 +220,7 @@
             if ( -l "$dir/$path" ) {

                 # Assume pseudo-installed
-                $this->{installedVersion} = 'HEAD';
+                $this->{installedVersion} = '9999.99_999';
             }
             last;
         }

</verbatim>

---++ Installation
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.


---++ Info

|  Author: | GeorgeClark |
|  Copyright &copy;: | Foswiki Contributors |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Algorithm::Diff</td><td align="left">&gt;=0</td><td align="left">May be required for lib/CPAN/lib/Text/Diff.pm</td></tr><tr><td align="left">Carp</td><td align="left">&gt;=0</td><td align="left">May be required for lib/CPAN/lib/Text/Diff.pm, lib/CPAN/lib/Text/Diff/Table.pm, lib/CPAN/lib/Text/Patch.pm</td></tr><tr><td align="left">Exporter</td><td align="left">&gt;=0</td><td align="left">May be required for lib/CPAN/lib/Text/Diff.pm, lib/CPAN/lib/Text/Patch.pm</td></tr><tr><td align="left">File::Copy</td><td align="left">&gt;=0</td><td align="left">May be required for lib/Foswiki/Configure/PatchFile.pm</td></tr><tr><td align="left">File::Path</td><td align="left">&gt;=0</td><td align="left">May be required for lib/Foswiki/Configure/PatchFile.pm</td></tr><tr><td align="left">File::Spec</td><td align="left">&gt;=0</td><td align="left">May be required for lib/Foswiki/Configure/PatchFile.pm</td></tr><tr><td align="left">Foswiki::Time</td><td align="left">&gt;=0</td><td align="left">May be required for lib/Foswiki/Configure/PatchFile.pm</td></tr></table> |
|  Version: | 1.5 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  1.5 (26 Dec 2012) | Foswikitask:Item12312: Add reporting of patch status,%BR%\
                       Foswikitask:Item12314: Add feature to reverse a patch.%BR%\
                       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 |
|  Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Support: | http://foswiki.org/Support/%TOPIC% |
Topic revision: r1 - 18 Nov 2013, UnknownUser
System
Copyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding BACCHUS Wiki? Send feedback