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.

New in OJS 2.1
--------------

In OJS 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.


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

The OJS source code is available in three forms: as patches against older
releases of OJS, from an anonymous CVS repository, and as a complete
stand-alone package.

Patching or updating from CVS is the recommended approach if you have made local
modifications to the system.

1. 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.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


2. CVS

If your instance of OJS was checked out from the PKP anonymous CVS repository
(see docs/README-CVS), you can update the OJS code using a CVS client.

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

    $ cvs update -r TAG

"TAG" should be replaced with the CVS 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. Full Package

It is also possible to upgrade by downloading the complete package for the
latest release of OJS:

    - Download and decompress the package from the OJS web site
    - Make a copy of the config.inc.php provided in the new package
    - 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
    - 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.



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 by running the following command from the OJS directory:

    $ php tools/upgrade.php upgrade


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
======================

OJS 2 represents a complete re-design and re-implementation of the Open Journal 
Systems project, and as such, it is not possible to directly upgrade a 1.x
system to 2.x.

Instead, a migration utility has been provided to allow content from OJS 1.x to
be imported into an installed 2.x system -- including most journal settings and
all user, issue, and article data.

Migration is only supported for OJS 1.1.5 and later. Older releases of OJS 1.x
must first be upgraded to a newer release of 1.x.

To migrate data from OJS 1.x to a 2.x system:

    - Install the latest release of OJS 2 onto the same server as the current
      OJS 1 installation
    - Run the migration command-line or web-based utility to import data


The migration utility can be used to either create a new OJS 2 journal with all
settings and data from an OJS 1 journal, or to import just users, issues, and
articles into an already existing OJS 2 journal.

Note that, depending on the amount of content in the journal to be imported, it
may take a long time for the migration utility to complete -- especially if your
system is configured to index full-text files.

1. Using the migration command-line tool:

    $ php tools/migrate.php [journal_path] [ojs1_path] [options]
    
   Options:
   
    journal_path  Journal path to create (E.g., "ojs")
                  If path already exists, all content except journal settings
                  will be imported into the existing journal
                  
    ojs1_path     Complete local filesystem path to the OJS 1 installation
                  (E.g., "/var/www/ojs")
                  
    options       importSubscriptions - import subscription type and subscriber
                  data
                  verbose - print additional debugging information
                  
   Examples:
   
    To import all data from "/var/www/ojs" into a new journal "import1":

        $ php tools/migrate.php import1 /var/www/ojs importSubscriptions
    
    To import just users, issues, and articles from "/var/www/ojs" into an
    existing journal "import2":     

        $ php tools/migrate.php import2 /var/www/ojs
   
   WARNING: If the CLI tool is executed as a different user than the Apache
   user, you will need to chown or chmod the public and uploaded files
   directories before (for the user running the tool) and afterwards (to
   Apache) to set the correct ownership/permissions.


2. Using the migration web-based tool:

   The web-based migration utility can be found under:
   
        Site Administration > Hosted Journals > Import From OJS 1

   The web-based tool is used nearly identically to the CLI tool.


Additional notes regarding migration:

    - After using the migration tool, edit and save the hosted journal settings
      under Site Administration, and proceed through and complete all Journal
      Setup steps under Journal Management -- there are a number of new and
      modified settings in OJS 2 compared to OJS 1
    - Any number of OJS 1.x journals can be imported into a single OJS 2
      instance (OJS 2 is designed as a multiple journal system)
    - OJS 2 requires both user usernames and email addresses to be unique (OJS
      1 did not enforce the latter restriction):
        - If a user already exists with the same username as an imported
          user, all imported data will be associated with the existing user
        - If a user already exists with the same email address as an
          imported user, the email address of the imported user will be
          prefixed with "ojs-<username>+" to ensure uniqueness -- such users
          can then be updated manually post-migration
    - Modified email templates and RST versions are not migrated due to the
      numerous revisions and enhancements to these components in OJS 2
    - Migrated subscription types are given a 12-month duration and public
      visibility by default -- these settings can be modified post-migration
    - OJS 2 currently does not support per-issue ordering of sections. If the
      ordering of the sections in your issues appears incorrect after importing,
      adjust the section ordering in Journal Management (all issues will have
      the same section ordering)


OJS 1.x features that are currently not supported in 2.x:

    - OJS 2 currently only includes an English localization (see the README for
      information on producing a translation for other languages)
    - Editorial/review board support is currently not supported, but may appear
      in a future release
    - Distinct "Book/Media Review" listings are not currently and are not likely
      to ever be supported
    - LOCKSS support is currently unavailable, but will likely appear in a
      future release
    - The journal statistics component is currently not implemented, but will be
      added to a future release
