From 306cd2315f9c83ff18103c5aaaa4dbccd08dadd5 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 5 May 2022 00:18:25 +0100 Subject: [PATCH] docs: Document format compatibility Signed-off-by: Ian Jackson --- docs/bundles.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++++ docs/gamespec.rst | 6 ++++++ docs/shapelibs.rst | 9 +++++++- 3 files changed, 65 insertions(+), 1 deletion(-) diff --git a/docs/bundles.rst b/docs/bundles.rst index 5ae65176..55703876 100644 --- 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 `__ 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] ` + - Status + - Changes + + * - ``1`` + - 0.x - `1.0.0 `_ + - 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 6ecbe7e4..d92908cc 100644 --- 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 0f06d360..c43a05c4 100644 --- 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 -- 2.30.2