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 major unstable protocol
versions as long as the requirements are held upon release.