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
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.
-**What makes up the interface?
-**How to read the CHANGES file?
+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.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
+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.