docs: Document format compatibility

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 5ae6517626d1da8be5cda30135d61f7d33913d0c..5570387602e1308756a8f12c2d281e307d3e5ea4 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -76,6 +76,13 @@ The top-level ``otter.toml`` contains the following keys:
    zipfile's name is not stored in the server.
    [string, mandatory]
 
+ * ``format``.  Identifies which version of this specification
+   the bundle was written to.  This is also used as a default for
+   further TOML files which are found in the bundle.
+   The current format version is ``1``.
+   [integer]
+   See `bundle compatibility`_.
+
 Newer versions of Otter may assign meanings to other keys.
 
 Bundle management
@@ -131,3 +138,47 @@ There are also several game spec examples, such as:
 
 Consult the `webserver directory listing <examples/>`__ for a complete
 list.
+
+
+.. _bundle-compatibility:
+
+Bundle compatibility
+---------------------
+
+The ``format`` key at the toplevel of many of Otter's TOML files
+declares which version of the Otter data formats and specifications
+the file adheres to.
+This allows old files to keep working, even as Otter evolves.
+
+If no format is specified for a file in a bundle, the bundle's
+overall format is taken.  However,
+it is a good idea for each file to contain its own ``format=``
+setting, so that the file doesn't change meaning when put into a
+different bundle with a different overall format version.
+
+The current version is ``format=1``.
+
+This table gives the format versions,
+and the corresponding versions of Otter.
+For full details of the earlier formats,
+follow the link to the latest published documentation for that format.
+
+.. list-table::
+  :widths: 8 15 11 66
+  :header-rows: 1
+
+  * - ``format``
+    - Otter :ref:`[1] <bundle-compatibility-otter-footnote>`
+    - Status
+    - Changes
+
+  * - ``1``
+    - 0.x - `1.0.0 <https://www.chiark.greenend.org.uk/~ianmdlvl/otter/1.0.0/docs/README.html>`_
+    - supported
+    - First release.
+      Note that ``format`` may be omitted in this version.
+
+.. _bundle-compatibility-otter-footnote:
+[1] The earliest version of Otter that supports this format,
+and the newest version which uses it as the primary format.
+(Currently, newer versions of Otter can read files in any older format.)

diff --git a/docs/gamespec.rst b/docs/gamespec.rst
index 6ecbe7e4de1b47a6abcd7590538ae2e755922691..d92908ccf1acbe950667e467a7b701760e90791a 100644 (file)
--- a/docs/gamespec.rst
+++ b/docs/gamespec.rst
@@ -28,6 +28,12 @@ level:
  * ``pieces``: Array of `Piece Specs`_.  Defines the initial pieces
    and their layout.  Each entry is a piece spec dictionary.
 
+ * ``format`` [integer]: Specifies which version of the Otter data
+   formats the spec file was written to.
+   This document describes ``format=1``.
+   See :ref:`bundle-compatibility`.
+
+
 Templating
 ``````````
 

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index 0f06d36086af4e57b83208741f28d9b5a2d984fb..c43a05c42ec4f1316ab270f2a0f3a62dc48581e8 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -72,7 +72,14 @@ piece it defines each face looks like, how big it is on the screen,
 whether and how the piece can be occulted, and what source image files
 are to be used to display it.
 
-The catalogue is a TOML file.  Its main contents is a dictionary
+The catalogue is a TOML file.
+
+The file should have a toplevel key ``format``, specifying which
+version of the Otter data formats the file was written to.
+This document describes ``format=1``.
+See `bundle compatibility`_.
+
+The catalogue's main contents is a dictionary
 ``groups``, mapping each group name to a sub-dict of parameters:
 
 Each catalogue is organised into named **groups**.  Each group defines