Added README file describing development procedures etc

The format used is (unverified) AsciiDoc.

Signed-off-by: Jonas Ådahl <jadahl@gmail.com>

1 files changed, 124 insertions, 0 deletions

diff --git a/README b/README
index be830cc..fd32371 100644
--- a/README
+++ b/README
@@ -1 +1,125 @@
 Wayland protocols
+-----------------
+
+wayland-protocols contains Wayland protocols that adds functionality not
+available in the Wayland core protocol. Such protocols either adds
+completely new functionality, or extends the functionality of some other
+protocol either in Wayland core, or some other protocol in
+wayland-protocols.
+
+A protocol in wayland-protocols consists of a directory containing a set
+of XML files containing the protocol specification, and a README file
+containing detailed state and a list of maintainers.
+
+Protocol directory tree structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Protocols may be 'stable', 'unstable' or 'obsolete', and the interface
+and protocol names as well as place in the directory tree will reflect
+this.
+
+A stable protocol is a protocol which has been declared stable by
+the maintainers. Changes to such protocols will always be backward
+compatible.
+
+An unstable protocol is a protocol currently under development and this
+will be reflected in the protocol and interface names. See <<Unstable
+naming convention>>.
+
+An obsolete protocol is a protocol that has either been replaced by some
+other protocol, or declared undesirable for some other reason. No more
+changes will be made to an obsolete protocol.
+
+Depending on which of the above state the protocol is in, the protocol
+is placed within the toplevel directory containing the protocols with the
+same state. Stable protocols are placed in the +stable/+ directory,
+unstable protocols are placed in the +unstable/+ directory, and obsolete
+protocols are placed in the +obsolete/+ directory.
+
+Protocol development procedure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To propose a new protocol, create a patch adding the relevant files and
+Makefile.am entry to the wayland-protocols git repository with the
+explanation and motivation in the commit message. Then send the patch to
+the wayland-devel@lists.freedesktop.org mailing list using
+'git send-email' with the subject prefix 'RFC wayland-protocols' or
+'PATCH wayland-protocols' depending on what state the protocol is in.
+
+To propose changes to existing protocols, create a patch with the
+changes and send it using 'git send-email' with a subject prefix
+describe above.
+
+If the changes are backward incompatible changes to an unstable protocol,
+see <<Unstable protocol changes>>.
+
+Unstable naming convention
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unstable protocols have a special naming convention in order to make it
+possible to make discoverable backward incompatible changes.
+
+An unstable protocol has at least two versions; the major version which
+are represents backward incompatible changes, and the minor versions,
+which represents backward compatible changes to the interfaces in the
+protocol.
+
+The major version is part of the XML file name and the protocol name in
+the XML, while a minor version is the version attribute of the interfaces
+in the protocol.
+
+The XML file and protocol name also has the word 'unstable' in them, and
+all of the interfaces in the protocol are prefixed with +z+ and
+postfixed with the major version number.
+
+For example, an unstable protocol called foo-bar with major version 2
+containing the two interfaces wl_foo and wl_bar both minor version 1 will
+a directory called +foo-bar/+ placed in the directory +unstable/+
+consisting of one file called +README+ and one called
++foo-bar-unstable-v2.xml+. The XML file will consist of two interfaces
+called +zwl_foo2+ and +zwl_foo2+ with the +version+ attribute set to +1+.
+
+Unstable protocol changes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+During the development of a new protocol it is possible that backward
+incompatible changes are needed. Such a change needs to be represented
+in the major and minor versions of the protocol.
+
+Assuming a backward incompatible change is needed, the procedure how to
+do so is the following:
+
+  . Make a copy of the XML file with the major version increased by +1+.
+  . Increase the major version number in the protocol XML by +1+.
+  . Increase the major version number in all of the interfaces in the
+    XML by +1+.
+  . Reset the minor version number (interface version attribute) of all
+    the interfaces to +1+.
+
+Backward compatible changes within a major unstable version can be done
+in the regular way as done in core Wayland or in stable protocols.
+
+Declaring a protocol stable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once it is decided that a protocol should be declared stable, meaning no
+more backward incompatible changes will ever be allowed, one last
+breakage is needed.
+
+The procedure of doing this is the following:
+
+  . Create a new directory in the +stable/+ toplevel directory with the
+    same name as the protocol directory in the +unstable/+ directory.
+  . Copy the final version of the XML that is the version that was
+    decided to be declared stable into the new directory. The target name
+    should be the same name as the protocol directory but with the +.xml+
+    prefix.
+  . Rename the name of the protocol in the XML by removing the
+    'unstable' part and the major version number.
+  . Remove the +z+ prefix and the major version number postfix from all
+    of the interfaces in the protocol.
+  . Reset all of the interface version attributes to +1+.
+  . Update the +README+ file in the unstable directory and create a new
+    +README+ file in the new directory.
+
+Releases
+~~~~~~~~
+Each release of wayland-protocols finalizes the version of the protocols
+to their state they had at that time. Between each release, backward
+incompatible changes can be made to both stable and unstable protocols
+as long as the requirements are held upon release.