.. include:: ./macros.inc
.. _#ug-appendix-file-format-versions:

35. File Format Versions
=========================================

This chapter includes a simple cross-reference to the file format versions in
recent AMPS releases. Using this guide, you can quickly determine whether your
installation will need to run ``amps_upgrade`` when changing versions.

+--------------+-------------+-------------------+---------------+------------------------+
| AMPS version | SOW version |   Journal version |  Acks version | Queue Metadata version |
+==============+=============+===================+===============+========================+
| 3.8          | v1.0        |   v3              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 3.9          | v1.0        |   v3              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 4.0          | v3.0        |   v7              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 4.3          | v3.0        |   v7              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.0          | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.2          | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.2.1        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.2.2        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.2.3        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.2.4        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.3.0        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.3.1        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.3.2        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.3.3        | v3.0        |   v8              |   v1.0        |                        |
+--------------+-------------+-------------------+---------------+------------------------+
| 5.3.4        | v3.0        |   v8              |   v1.0        | v001                   |
+--------------+-------------+-------------------+---------------+------------------------+

The ``amps_upgrade`` tool is provided for versions of AMPS 5.0 and earlier.
The ``amps_upgrade`` tool updates the format of the data in the files that
AMPS maintains. If there has been no version change to the format of the data,
it is not necessary to run the tool to upgrade an AMPS instance.

Notice that, while this chart describes the format of the files, AMPS versions
may also change or extend the content of the files. In these cases, AMPS
is guaranteed to be forward-compatible. That is, a given version of AMPS can
process a file of the same file format version created on an earlier version
of AMPS. However, later versions of AMPS may include changes in the content
of the file that are not recognized by earlier versions of AMPS. This means
that downgrading a file between major/minor versions of AMPS is not
supported.

.. caution::

    The contents of AMPS files are not guaranteed to be backward
    compatible across changes to the major or minor version number.
    That is, while an AMPS instance of version X.4 can successfully
    load a SOW file created by version X.3, the version X.3 instance
    may not be able to process a file created or updated by the
    X.4 version.

    Contact 60East support for guidance if you intend to downgrade
    an instance of AMPS to an earlier version.

