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

If you accidentally upgraded your Sumatra version without exporting the old project first, you will need to roll back to the previous version in order to be able to do the export. See below for an example how to do this using pip.

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 .smt directory: records_export.json and project_export.json.

You can now delete export.py

For Sumatra 0.4 and later

Run:

$ smt export

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

Install the new version and upgrade

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

$ pip install --upgrade sumatra

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

Then run:

$ smt upgrade

The original .smt directory will be copied to a time-stamped directory, e.g. .smt_backup_20140209132422.

Downgrading an accidentally upgraded Sumatra to export the project

Exporting a project will need to be done with the same Sumatra version that the project was run with last. If you accidentally upgraded your Sumatra version without exporting the old project first, you will need to roll back to the previously installed version. You can explicitly specify a version number with pip as follows:

$ pip install sumatra==0.5.3

Replace 0.5.3 with the correct version number for your project. In case you are unsure, it may help to run the following command in your project directory:

$ cat .smt/project | grep sumatra_version