Upgrading EPM Packages - Revision history

Kgoetz: link to https://semver.org

2018-09-11T23:10:13Z

link to https://semver.org

Th.lauke@arcor.de: usefull category added

2015-01-16T13:42:29Z

usefull category added

DaveTarrant: /* Example */

2010-12-14T17:08:55Z

‎Example

DaveTarrant: /* Example */

2010-12-14T16:45:58Z

‎Example

DaveTarrant: Created page with '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.…'

2010-12-14T16:45:50Z

Created page with '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.…'

New page

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.

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

← Older revision		Revision as of 23:10, 11 September 2018
Line 4:		Line 4:

	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.		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.
		+
		+	For further information on Semantic Versioning see https://semver.org.

	==Bugfix Releases==		==Bugfix Releases==

← Older revision		Revision as of 13:42, 16 January 2015
Line 87:		Line 87:

	If people are upgrading from 0.0.1 to 0.0.5 then potentially 4 of these upgrade methods will be called.		If people are upgrading from 0.0.1 to 0.0.5 then potentially 4 of these upgrade methods will be called.
		+
		+	[[Category:EPrints_Bazaar]]

← Older revision		Revision as of 17:08, 14 December 2010
Line 84:		Line 84:


−	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.	+	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.		If people are upgrading from 0.0.1 to 0.0.5 then potentially 4 of these upgrade methods will be called.

@@ Line 50: / Line 50: @@
          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