=======================
Upgrading your projects
=======================

Since new versions of Sumatra extend its capabilities, and may change the way
records are stored, when you install a new version of Sumatra you will need to
upgrade your existing Sumatra projects to work with the new version.

In future, this will probably be done automatically, but while Sumatra is still
rapidly evolving we are keeping it as a simple manual process to minimize the
risk of data loss.

Export using the old version
----------------------------

Before installing the new version of Sumatra, you must export your project to a
file.

For Sumatra 0.1-0.3
~~~~~~~~~~~~~~~~~~~

First, download export.py_ to your project directory, then run::

    $ python export.py
    
This will export your project in JSON format to two files in the :file:`.smt` directory:
:file:`records_export.json` and :file:`project_export.json`.

You can now delete :file:`export.py`

For Sumatra 0.4 and later
~~~~~~~~~~~~~~~~~~~~~~~~~

Run::

    $ smt export

This will export your project in JSON format to two files in the :file:`.smt` directory:
:file:`records_export.json` and :file:`project_export.json`.


Install the new version and upgrade
-----------------------------------

Now you can install the new version, e.g. with::

    $ pip install --upgrade sumatra
    
or::
    
    $ easy_install -U sumatra

(or you can install from source, as explained in doc:`installation`).


Then run::

    $ smt upgrade
    
The original :file:`.smt` directory will be copied to a time-stamped directory, e.g.
:file:`.smt_backup_20110209132422`.


.. _export.py: http://neuralensemble.org/trac/sumatra/browser/tools/export.py?format=txt