tome / doc / compat.txt

              The Tome Version Numbering and Compatibility Plan

                         Overview of Version Numbers

Tome uses a 4 part version number, with each part corresponding to a
particular class of changes, and in general correspond to a specific level of

The 4 part version is of the form: <Major>.<minor>.<patch>.<semantic>, or more
succinctly: "M.n.p.s".

The Major version ("M") is the most significant component: a change to the
Major version number generally represents a major change to the program,
but more specifically it indicates a *complete* loss of compatibility. In
other words, a Major version change will remove an existing interface.
Software that interfaces with a particular version of tome will not (in
general) work with a different Major version of tome.

The minor version ("n") is next most significant, after Major. A change to the
minor version number specifically indicates an addition to the interface, and
a loss of *forwards* compatibility, but preservation of *backwards*
compatibility. Software that interfaces with a particular version of tome will
not work with versions that have an earlier minor version, but will work if
the major version is the same, and the minor version is greater or equal.

The patch version ("p") is the least significant version that actually changes
the code. A change to the patch version preserves both backwards *and*
forwards compatibility, so the interface is perfectly preserved. This can
cover any number of things, from bug fixes, to optimizations, even added
capabilities that don't effect the interface.

Lastly, the semantic version ("s") refers to changes to the package that don't
actually effect the code. This might be added documentation or comments in the
code, or something similar. You aren't likely to see changes to the semantic
version very often, because they usually don't justify a new release.

Version number components are implicitly 0 if unspecified, so 1.0 and 1.0.0
are the same version. Generally speaking, trailing zeros beyond the minor
version number are left omitted for brevity. However, the Major version number
alone typically refers to a major version of the interface, so version 1
refers to the major interface of all 1.x.x.x versions, but version 1.0
specifically refers to version

                              The Release Number

In addition to the version number, each official release is given an
incremental release number. This makes it easy to see how many releases you've
missed, since that is not apparent from the version number. The release
numbers start at 1 and increment by 1 with each release.

                               The CHANGES File

The CHANGES.txt file at the top level of the source package describes the
significant changes of each released version. The file is divided by release,
with the first line of each section specifying the release number, the version
number, and the release date. Following this is a list of the changes for that
release. Each item starts with an indicator of what type of change is what:
Major (M), minor (n), patch (p), or semantic (s). Then there's a description
of the change, and lastly is an indication of what mercurial changesets are
relevant to the change (abbreviated "cs"). If there are a large number of
changesets, they will not all be listed; sometimes a branch name will be

                          What Defines the Interface

Since all the version numbers are defined based on how they affect the
interface, it's worth mentioning what is is included in the interface.

There are several aspects which we count among the program's interface. The
first is the arguments and options to the command line programs. Then there's
the actual programming interface to the python modules (the API). Lastly,
there are the template iterfaces. This is the interface for the templates that
some of the output writers use and includes user-supplied template and
resource files as well as templ variables or functions that are predefined by
tome before processing the templates.

What are not (currently) included in the interface are the specifics of the
generated output. In other words, do not assume that specific files will be
created or that you can parse the output consistently, beyond what is defined
for the specific output medium (e.g., if the output writer generates an XHTML
document, then it can be parsed as XHTML, but do not assume that Tome specific
elements will obey a specific interface). Also note that for HTML based output
(such as EPUB) the classes and ids that are used for each element follow
general guidelines, but we do not attempt to hold these to an interface (at
least not yet).

Also not included in the interface is the XML output format for a tome
document. This format has its own version number which uses the same scheme,
but it is versioned separately from the tome package.

# vim: set tw=78: