Upgrading EPM Packages

EPM package guidelines state that you should use semantic version numbers for you package versions. This also makes upgrades easier. This page discusses why and gives an example.

Semantic Versioning

Semantic version numbers take the form X.X.X where all X's are numbers and can each be as large as you like. Another way of writing this version number is Major.Minor.Bugfix and is how we shall refer to them from now on.

Bugfix Releases

Bugfix releases of Bazaar packages should introduce NO extra functionality, they should also be able to be installed with NO user interaction. This way they can auto-update on the server if the user has specified this is OK.

Minor Releases

Minor releases can add functionality but as a guide should not change the features of that release or the underlying data model (if there is one). Minor release can require interaction from the user to install.

Major Releases

These are really up to the user to install and could completely change the functionality of a package (although not recommended). At this point you can do what you like :)

Upgrade Methodology

When an upgrade is done performed upon a package the postinst method is not called rather an upgrade method is called and passed the two version numbers. These version numbers correspond to the old version being upgraded and the new version being installed respectively.

Files on Disk Upgrade

This is the first stage of any upgrade.

• Any files belonging to the old version are removed or replaced by new versions.
• Any new files which were not there before are added.
• Any errors (e.g. files not under package management cos they have changed) results in an error and the old files are put back and the upgrade aborts.

API Calls

These would have been performed initially by the POSTINST method. However neither this nor the PRERM method are called during an upgrade. Any changes required between versions must be defined in the upgrade method.

Data and Datasets

Datasets are defined in config files, thus any dataset changes are applied.

No data is lost unless the field containing that data is no longer defined by any config file.

Interactive Install/Upgrade/Remove will allow the users to change this behaviour and keep the data even if it actually becomes inaccessible due to nothing in EPrints understanding it.

Example

The starting point for this is our Screen plug-in where the POSTINST and PRERM methods are defined (see XML manipulation of the EPrints Workflow using a Bazaar Package).

To enable upgrades we simply add an upgrade sub alongside these methods:

 sub allow_action_upgrade
 {
       my ( $self ) = @_;
 
       return 1;
 }
 
 # The upgrade method, this will call all upgrade subs individually between the old version number and the new version number.
 sub action_upgrade
 {
       my ( $self, $old_version_number, $new_version_number ) = @_;
   
       my @versions = qw(
                       0.0.1
                       0.0.2
       );
       
       for(my $i = 0; $i < $#versions; ++$i)
       {
              if( $old_version_number eq $versions[$i] )
              {
                       no strict 'refs';
                       my $f = "upgrade_".$versions[$i]."_to_".$versions[$i+1];
                       $f =~ s/\./_/g;
                       &$f( $self );
                       $old_version_number = $versions[$i+1];
              }
       }
 }
  
 sub upgrade_0_0_1_to_0_0_2
 {
       my ( $self ) = @_;
 
       print STDERR "IN THE UPGRADE ROUTINE FOR 0.0.1 to 0.0.2 \n\n";
 
       # Add your API calls POSTINST like stuff here to upgrade versions. 
 }

So all you need to do is define potentially lots of upgrade_X_X_X_to_X_X_Z routines to handle all the upgrades and add this version number (which needs an upgrade routine).

If people are upgrading from 0.0.1 to 0.0.5 then potentially 4 of these upgrade methods will be called.