Upgrading Bazaar Packages (How it Works)
This page outlines what happens when you upgrade an EPrints Bazaar package, more importantly it outlines the difference between Upgrade and Disable.
The Upgrade Process
The upgrade process consists of the following stages, if any of which fail then the package will not be upgraded.
Note that some of the stages have the potential to succeed incorrectly which is when bugs occur.
The main bulk of this process is detailed in perl_lib/EPrints/Plugin/Screen/Admin/EPM/Available.pm
Stage 1 - Retrieve Installed EPM
From /lib only the installed epm is retrieved and hashes for each of the files generated.
NOTE: If you have made changes to the epm in /lib in order to do some development, don't expect an upgrade on the running repository to work, create another one!
Stage 2 - Disable Unchanged
NOTE: This only refers to the files that get installed in the repository archive path. e.g. archive/foo/cfg/cfg.d/package_cfg.pl
Basically if the files installed in the repository haven't changed then they are removed. If they have changed then they are left unchanged or saved at .pl.epmsave.
Stage 3 - Uninstall Existing
At this stage the current epm files in /lib are removed. The hashes will match as this is where you got them from at stage 1!
Stage 4 - Install new EPM
This stage installs the new EPM in lib, note that it will not enable it, thus no files are copied to the repository directory, these are still not present as they were deleted in Stage 2.
At this stage the repository config is checked (not loaded) to see if the epm will cause fatal errors.
If it can load, then it is loaded (unless you are upgrading).
Stage 5 - Upgrade
This stage enables the epm, installing the repository files and calling a full reload.
Before it does this reload, the current counters and datasets are retrieved from the running config. This is the config that was running before Stage 1, before this whole process started, thus it will list datasets installed by the old epm.
A reload is then done and the old datasets and counters are compared to those required now. Any changes are then applied.
If fields and counters have been added, these are added. If fields and counters have been removed, these are removed.
This means an upgrade will work and not delete data
Note: If the repository object does not have any knowledge of orphaned data in the database then it won't delete it as this will not appear as a change. No knowledge before = No knowledge now = no change.
If you choose to disable/un-install before installing a new version of a bazaar package then your data will automatically be removed when the repository is reloaded!
To keep a dataset, you have to keep it defined in the repository config.