doc: Add a section on interface and protocol object versioning

There have been a lot of questions asked lately about versioning of
interfaces and protocol objects.  This addition to the documentation should
clear up some of those questions.

Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>

1 files changed, 61 insertions, 0 deletions

diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index 74f2aea..b79b6be 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -164,6 +164,67 @@
     </para>
   </section>
   <xi:include href="ProtocolInterfaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <section id="sect-Protocol-Versioning">
+    <title>Versioning</title>
+    <para>
+      Every interface is versioned and every protocol object implements a
+      particular version of its interface.  For global objects, the maximum
+      version supported by the server is advertised with the global and the
+      actual verion of the created protocol object is determined by the
+      version argument passed to wl_registry.bind().  For objects that are
+      not globals, their version is inferred from the object that created
+      them.
+    </para>
+    <para>
+      In order to keep things sane, this has a few implications for
+      interface versions:
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    The object creation hierarchy must be a tree.  Otherwise,
+	    infering object versions from the parent object becomes a much
+	    more difficult to properly track.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    When the version of an interface increases, so does the version
+	    of its parent (recursively until you get to a global interface)
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    A global interface's version number acts like a counter for all
+	    of its child interfaces.  Whenever a child interface gets
+	    modified, the global parent's interface version number also
+	    increases (see above).  The child interface then takes on the
+	    same version number as the new version of its parent global
+	    interface.
+	  </para>
+	</listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      To illustrate the above, consider the wl_compositor interface.  It
+      has two children, wl_surface and wl_region.  As of wayland version
+      1.2, wl_surface and wl_compositor are both at version 3.  If
+      something is added to the wl_region interface, both wl_region and
+      wl_compositor will get bumpped to version 4.  If, afterwards,
+      wl_surface is changed, both wl_compositor and wl_surface will be at
+      version 5.  In this way the global interface version is used as a
+      sort of "counter" for all of its child interfaces.  This makes it
+      very simple to know the version of the child given the version of its
+      parent.  The child is at the highest possible interface version that
+      is less than or equal to its parent's version.
+    </para>
+    <para>
+      It is worth noting a particular exception to the above versioning
+      scheme.  The wl_display (and, by extension, wl_registry) interface
+      cannot change because it is the core protocol object and its version
+      is never advertised nor is there a mechanism to request a different
+      version.
+    </para>
+  </section>
   <section id="sect-Protocol-Connect-Time">
     <title>Connect Time</title>
     <para>