Upgrading an OJS Installation
-----------------------------

Note: backing up your current data files and database is strongly recommended
prior to upgrading OJS.

If you are using PHP Safe Mode, please ensure that the max_execution_time
directive in your php.ini configuration file is set to a high limit. If this
or any other time limit (e.g. Apache's "Timeout" directive) is reached and
the upgrade process is interrupted, manual intervention will be required.


======================
Upgrading from OJS 2.x
======================

Upgrading to the latest version of OJS involves two steps:

    - Obtaining the latest OJS code
    - Upgrading the OJS database

It is highly recommended that you also review the release notes (docs/RELEASE)
and other documentation in the docs directory before performing an upgrade.


Upgrade Notes
-------------

If you are upgrading from a version prior to 2.1, the caching directories for
help, locale data, database queries, templates, etc. have been moved into a
single "cache" directory. If you are upgrading from a prior release of OJS 2.x
to OJS 2.1, you will need to ensure that the new cache directory exists and can
be written by the web server. With-out doing this, your installation may work,
but it may perform poorly. See docs/README, under Installation, for a list of
directories that must be writeable by the web server.


Stats Migration
---------------

To be able to run the upgrade process and to correctly migrate the old statistics
data, you will have to download the geolocalization database. To install it 
you can execute the following steps:

Linux:
1 - open a shell prompt
2 - go into OJS installation’s base directory
2 - wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
3 - gunzip GeoLiteCity.dat.gz
4 - mv GeoLiteCity.dat plugins/generic/usageStats

Windows
1 - download the file http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz 
2 - decompress it using any decompression tool into plugins/generic/usageStats directory

In both cases the complete path to the installed database file should be 
plugins/generic/usageStats/GeoLiteCity.dat

Warning: If you have a very large set of Timed Views entries, 
the migration process can take hours. 
  

Obtaining the latest OJS code
-----------------------------

The OJS source code is available in three forms: as a complete stand-alone 
package, from read-only github access, and as patches against older releases 
of OJS.

1. Full Package

If you have not made local code modifications to the system, upgrade by 
downloading the complete package for the latest release of OJS:

    - Download and decompress the package from the OJS web site
    - Move or copy the following files and directories from your current OJS
      installation:
        - config.inc.php
        - public/
        - Your uploaded files directory ("files_dir" in config.inc.php), if it
          resides within your OJS directory
    - Synchronize new changes from config.TEMPLATE.inc.php to config.inc.php
    - Replace the current OJS directory with the new OJS directory, moving the
      old one to a safe location as a backup
    - Be sure to review the Configuration Changes section of the release notes
      in docs/release-notes/README-(version) for all versions between your
      original version and the new version. You may need to manually add
      new items to your config.inc.php file.

Updating from github is the recommended approach if you have made local
modifications to the system.

2. git

If your instance of OJS was checked out from github (see docs/README-GIT),
you can update the OJS code using a git client.

To update the OJS code from a git check-out, run the following command from
your OJS directory:

    $ git rebase --onto <new-release-tag> <previous-release-tag>

This assumes that you have made local changes and committed them on top of
the old release tag. The command will take your custom changes and apply
them on top of the new release. This may cause merge conflicts which have to
be resolved in the usual way, e.g. using a merge tool like kdiff3.

"TAG" should be replaced with the git tag corresponding to the new release.
OJS release version tags are of the form "ojs-MAJOR_MINOR_REVSION-BUILD".
For example, the tag for the initial release of OJS 2.1.0 is "ojs-2_1_0-0".

Consult the README of the latest OJS package or the OJS web site for the
tag corresponding to the latest available OJS release.

Note that attempting to update to an unreleased version (e.g., using the HEAD
tag to obtain the bleeding-edge OJS code) is not recommended for anyone other
than OJS or third-party developers; using experimental code on a production
deployment is strongly discouraged and will not be supported in any way by
the OJS team.

3. Patch

Patch files for older releases of OJS can be downloaded from the OJS web site.

To update by patching, download the appropriate patch file for your current
version of OJS and run the following command from your OJS directory:

    $ patch -p1 < PATCH_FILE

"PATCH_FILE" should be replaced with the path to the decompressed patch file
that was downloaded, e.g. "ojs-2.0_to_2.0.1.patch".

Alternatively, OJS 2.0.1 and later provide a command-line tool to automatically
download and apply the appropriate patch to upgrade to the latest release. To
use this tool run the following command from your OJS directory:

    $ php tools/upgrade.php patch

Note that this will require the GNU patch tool to be installed. GNU patch is
included in most *NIX distributions, and is available for Windows and Solaris
as a download. Windows users may need to work around a patch bug by converting
the line-endings in the patch file from UNIX to DOS; to do this, open the patch
file in Notepad and save it again.

Patch upgrades will NOT include any binary files that were introduced in the
new version, i.e. any GIF images that are needed in the new version but were
not included in the old version. To find a list of binaries that should be
manually added after applying the patch, search the patch file for lines like:
"Binary files (filename here) differ" (not including the quotes). These files
can be found in the distribution archive.

WARNING: The patch tool may leave files with ".orig" or ".rej" suffixes in your
installation. Please ensure that these do not expose any unintended system
information, particularly in the case of config.inc.php.orig (which may be
created in your installation's root directory).


Applying the Latest Recommended Patches
---------------------------------------

Starting with OJS version 2.3.3-2, the Public Knowledge Project development 
team maintains a publicly-available list of recommended patches for each 
release. These will add no new functionality and will typically consist of small, 
easy-to-read patches for specific issues. A Recommended Patches list for your
version of OJS  can be found on the PKP development wiki: 

    <http://pkp.sfu.ca/wiki/index.php/OJS_Recommended_Patches> 

Regardless of the method you used to download and apply the official system 
files, you will also want to review the list of recommended patches specific 
to your OJS version, and apply as necessary.

To apply a recommended patch, open the bug report and download the attached 
patch file(s). (Note that bug reports can quite often include a number of 
patches, some relevant to the application (ie. OJS) and version you are 
running, and some not. Ensure that you download all and only the patches 
specific to your application and version.) For each patch you download, 
first attempt a dry-run application of the patch, to ensure that it applies 
cleanly: 

    $ patch -p1 --dry-run < PATCH_FILE

If the patch applies cleanly, then run the following command, which will
actually apply the patch: 

    $ patch -p1 < PATCH_FILE

"PATCH_FILE" should be replaced with the path to the patch file that was 
downloaded, e.g. "6276-ojs.patch".



Upgrading the OJS database
--------------------------

After obtaining the latest OJS code, an additional script must be run to
complete the upgrade process by upgrading the OJS database and potentially
executing additional upgrade code.

This script can be executed from the command-line or via the OJS web interface.

1. Command-line

If you have the CLI version of PHP installed (e.g., /usr/bin/php), you can
upgrade the database as follows:

    - Edit config.inc.php and change "installed = On" to "installed = Off"
    - Run the following command from the OJS directory (not including the $):
      $ php tools/upgrade.php upgrade
    - Re-edit config.inc.php and change "installed = Off" back to
       "installed = On"

2. Web

If you do not have the PHP CLI installed, you can also upgrade by running a
web-based script. To do so:

    - Edit config.inc.php and change "installed = On" to "installed = Off"
    - Open a web browser to your OJS site; you should be redirected to the
      installation and upgrade page
    - Select the "Upgrade" link and follow the on-screen instructions
    - Re-edit config.inc.php and change "installed = Off" back to
       "installed = On"




======================
Migrating from OJS 1.x
======================

As of OJS 2.3, the migration tools to upgrade from OJS 1.x have been removed.
To migrate content from OJS 1.x, you'll need to first migrate via an
intermediate version (i.e. OJS 2.2.3). See the docs/UPGRADE document in that
release for further instructions. It is recommended that you use the most
recent available pre-2.3 release for the migration.
