diff --git a/ChangeLog b/ChangeLog
index 0499858c7..b9bfa86d6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2005-09-02  Carl Worth  <cworth@cworth.org>
+
+	* doc/public/tmpl/cairo-version.sgml: Add description of cairo's
+	versioning scheme.
+
 2005-09-02  Carl Worth  <cworth@cworth.org>
 
 	* src/cairo-cache-private.h:
diff --git a/doc/public/tmpl/cairo-version.sgml b/doc/public/tmpl/cairo-version.sgml
index 2fb1b9546..812eb3013 100644
--- a/doc/public/tmpl/cairo-version.sgml
+++ b/doc/public/tmpl/cairo-version.sgml
@@ -2,12 +2,112 @@
 Version Information
 
 <!-- ##### SECTION Short_Description ##### -->
-Compile and run time version checks
+Compile-time and run-time version checks.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Cairo has a three-part version number scheme. In this scheme, we use
+even vs. odd numbers to distinguish fixed points in the software
+vs. in-progress development, (such as from CVS instead of a tar file,
+or as a "snapshot" tar file as opposed to a "release" tar file).
 </para>
+<para>
+<informalexample><programlisting>
+ _____ Major. Always 1, until we invent a new scheme.
+/  ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (CVS)
+| /  _ Micro. Even/Odd = Tar-file/CVS
+| | /
+1.0.0
+</programlisting></informalexample>
+</para>
+<para>
+Here are a few examples of versions that one might see.
+<informalexample><programlisting>
+Releases
+--------
+1.0.0 - A major release
+1.0.2 - A subsequent maintenance release
+1.2.0 - Another major release
+
+Snapshots
+---------
+1.1.2 - A snapshot (working toward the 1.2.0 release)
+
+In-progress development (eg. from CVS)
+--------------------------------------
+1.0.1 - Development on a maintenance branch (toward 1.0.2 release)
+1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release)
+</programlisting></informalexample>
+</para>
+
+<refsect2>
+<title>Compatibility</title>
+<para>
+The API/ABI compatibility guarantees for various versions are as
+follows. First, let's assume some cairo-using application code that is
+successfully using the API/ABI "from" one version of cairo. Then let's
+ask the question whether this same code can be moved "to" the API/ABI
+of another version of cairo.
+</para>
+
+<para>
+Moving from a release to any later version (release, snapshot,
+development) is always guaranteed to provide compatibility.
+</para>
+
+<para>
+Moving from a snapshot to any later version is not guaranteed to
+provide compatibility, since snapshots may introduce new API that ends
+up being removed before the next release.
+</para>
+
+<para>
+Moving from an in-development version (odd micro component) to any
+later version is not guaranteed to provide compatibility. In fact,
+there's not even a guarantee that the code will even continue to work
+with the same in-development version number. This is because these
+numbers don't correspond to any fixed state of the software, but
+rather the many states between snapshots and releases.
+</para>
+</refsect2>
+
+<refsect2>
+<title>Examining the version</title>
+<para>
+Cairo provides the ability to examine the version at either
+compile-time or run-time and in both a human-readable form as well as
+an encoded form suitable for direct comparison. Cairo also provides a
+macro (CAIRO_VERSION_ENCODE) to perform the encoding.
+</para>
+
+<para>
+<informalexample><programlisting>
+Compile-time
+------------
+%CAIRO_VERSION_STRING	Human-readable
+%CAIRO_VERSION		Encoded, suitable for comparison
+
+Run-time
+--------
+cairo_version_string()	Human-readable
+cairo_version()		Encoded, suitable for comparison
+</programlisting></informalexample>
+</para>
+
+<para>
+For example, checking that the cairo version is greater than or equal
+to 1.0.0 could be achieved at compile-time or run-time as follows:
+
+<informalexample><programlisting>
+##if %CAIRO_VERSION >= %CAIRO_VERSION_ENCODE(1, 0, 0)
+printf ("Compiling with suitable cairo version: %%s\n", CAIRO_VERSION_STRING);
+##endif
+
+if (cairo_version() >= %CAIRO_VERSION_ENCODE(1, 0, 0))
+    printf ("Running with suitable cairo version: %%s\n", cairo_version_string ());
+</programlisting></informalexample>
+</para>
+</refsect2>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>