ocPortal Tutorial: Performing an upgrade
Written by Chris Graham, ocProducts
This tutorial will give background information for this process of upgrading ocPortal. ocProducts does release basic details with the news pieces associated with a new release, but further information will be given here so that you may gain a further understanding.Table of contents
Types of upgrade
When we make a release we will state whether we recommend users upgrade to it. If we have corrected a security issue, or a major bug (such as one that causes data loss), we are likely to strongly recommend upgrade. We usually list the main changes made in a releases, but do not explicitly detail vulnerabilities as it makes it a bit too easy for casual hackers.Upgrades may be roughly categorised under:
- patch releases – these are likely to involve bug fixes, with very few, if any new features. Any new features would have been implemented solely to provide important functionality that was obviously missing. Patch releases are very easy to upgrade to
- feature releases – these are likely to include many new features; the quantity of new features will depend on the difference in version numbers between releases. Minor releases are usually easy to upgrade to
- or, major releases – these are likely to involve many architectural changes, as well as new features; major releases are less common, as we need to perform additional testing for them which takes a long length of time – we therefore try to avoid architectural changes other than in large batches
It is recommended that you do not 'jump over' major releases (e.g. v2 to v4, jumping over v3) that you do not feel you need (or did not have time to upgrade to), as the chance is higher of an upgrade process bug being present in unusual upgrade jumps. In theory, it should work without issue, as the process has been designed very carefully, but in practice, it is very easy for a very minor glitch to cause major problems that need manual resolution: in such an event, we would fix the problem, either directly, or by mass provision of a script, but it would be an inconvenience.
The upgrade process
Important note
If you are jumping over major versions against our advice, you will actually need to upload all files from the upgrade-target versions manual installer, except info.php and install.php.
- taking a full backup (just in case a problem occurs) – better safe than sorry. This is also useful in case you overwrite files that you have edited: either due to these files being in locations with no override support, or due to changes being made without using the proper override mechanism
- closing your website from the Admin Zone
- uploading files from a zip we have made of changed files since the last major or sometimes feature release (the base version will be stated)
- if you have made any ocPortal source code customisations, you should use a 'dif' tool to reincorporate your changes into the latest versions of our files, and recreate your override file from this
- for a major upgrade, resolving any problems with custom code that is no longer architecturally correct
- running http://my-base-url/upgrader.php, in order to empty caches of out-dated information and to force any upgrade code (which may be scattered across many modules) to execute, as well as to perform checks:
- resolving any conflicts with templates, as necessary (for example, if there was a change in the verbatim version of a template, and the upgraded website had also changed that template, then changes might [depending on importance] need to be incorporated manually
- performing any necessary chmodding (fixing file permissions) for new files and directories that require it (or run fixperms.sh if you have Linux shell access)
- removing any files from previous versions of ocPortal that are no longer required
- move or rename any files as indicated
- clearing caches
- re-opening your website from the Admin Zone
Assistance
Upgrading is inherently complex, as it is close to programming in the sense that low-level changes are being made to the structure of the website. This is unfortunate but inevitable, and due to ocPortal's openly configurable and overridable (at the code level) nature, we would have an extremely hard time trying to automate the process beyond what the upgrade system (the stage launched by running upgrader.php) already does.If you require assistance for an upgrade, consider our Experts by the hour service.