Patch, Don’t Copy

The example I’ll use in this article is very abstract as it applies in a number of areas and to a number of files of different formats.  It concerns how when you upgrade, how to make sure you keep both 1) your changes and 2) incorporate our changes.

For the purposes of the example, for the name of files I’ll refer to 4 files vCurrentStandard, vNextStandard, vCurrentCustomization, vNextCustomization.  Current or Next refers to two different versions, whilst Standard refers to what we ship and Customization to how you might have modified it.

The files I am referring to, where you might have used these as the base of your file include …

• $FGLDIR/etc/fglprofile
• $FGLDIR/lib/default.4st
• $FGLDIR/lib/default.4ad
• $FGLASDIR/etc/as.xcf

The trap developers fall into is that they might take vCurrentStandard and apply their changes to produce vCurrentCustomization.  Then at upgrade time, they copy vCurrentCustomization to the new release.  In doing this, they will lose any changes we have made to the underlying standard file between releases.  The mindset should be to patch changes.

There are two approaches you can take, you can patch the changes to the standard to your customization, or alternatively patch your customizations onto the new standard.

With a very simple example, let says the original file (vCurrentStandard) was

#! vCurrentStandard
A
B
C
D

Lets say you have modified this by changing B to B2  so that vCurrentCustomizaton is

#! vCurrentCustomziation
A
B2
C
D

Let’s say our standard changes were to change C to C2.  So vNextStandard is

#! vNextStandard
A
B
C2
D

The mistake is to copy vCurrentCustomisation as vNextCustomisation  as the standard changes will be lost.  In the example, you would still have C and not C2

The technique is to patch.  Either starting with vCurrentCustomisation and patching differences in the standard …

A   
B2  
C   c C2
D

… to give …

#! vNextCustomisation
A
B2
C2
D

… or to start with vNextStandard and patch differences in the customisation

A  
B  c B2 
C2 
D

… to give …

#! vNextCustomisation
A
B2
C2
D

Hopefully you can see that vNextCustomization is the same and incorporates both the changes to the standard and your customization.

The example is very simple but same principals apply wether you have modified a line, or added or deleted a line.  Where it gets complex is when both your customization and our changes have modified the same line, and then you have to manually determine what the new customized line should be.

I haven’t given any commands but in Unix/Linux/OSX shell environments the important commands are

• diff – outputs the difference between two files, when saved this is known as a patch file
• patch – applies a patch file to a file

So in the above

diff vCurrentStandard vNextStandard > standard.diff
patch -o vNextCustomziation vCurrentCustomization standard.diff

or

diff vCurrentStandard vCurrentCustomization > customization.diff
patch -o vNextCustomization vNextStandard customization.diff

There are other commands you can use, for example some specialise with xml files.

Graphically what I have attempted to explain above, can be shown with these 3 images.  Copying your customisation as the new customisation is bad …