1Wayland protocols
2-----------------
3
4wayland-protocols contains Wayland protocols that add functionality not
5available in the Wayland core protocol. Such protocols either add
6completely new functionality, or extend the functionality of some other
7protocol either in Wayland core, or some other protocol in
8wayland-protocols.
9
10A protocol in wayland-protocols consists of a directory containing a set
11of XML files containing the protocol specification, and a README file
12containing detailed state and a list of maintainers.
13
14Protocol directory tree structure
15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16Protocols may be 'stable', 'unstable' or 'deprecated', and the interface
17and protocol names as well as place in the directory tree will reflect
18this.
19
20A stable protocol is a protocol which has been declared stable by
21the maintainers. Changes to such protocols will always be backward
22compatible.
23
24An unstable protocol is a protocol currently under development and this
25will be reflected in the protocol and interface names. See <<Unstable
26naming convention>>.
27
28A deprecated protocol is a protocol that has either been replaced by some
29other protocol, or declared undesirable for some other reason. No more
30changes will be made to a deprecated protocol.
31
32Depending on which of the above states the protocol is in, the protocol
33is placed within the toplevel directory containing the protocols with the
34same state. Stable protocols are placed in the +stable/+ directory,
35unstable protocols are placed in the +unstable/+ directory, and
36deprecated protocols are placed in the +deprecated/+ directory.
37
38Protocol development procedure
39~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40To propose a new protocol, create a patch adding the relevant files and
41Makefile.am entry to the wayland-protocols git repository with the
42explanation and motivation in the commit message. Then send the patch to
43the wayland-devel@lists.freedesktop.org mailing list using
44'git send-email' with the subject prefix 'RFC wayland-protocols' or
45'PATCH wayland-protocols' depending on what state the protocol is in.
46
47To propose changes to existing protocols, create a patch with the
48changes and send it to the list mentioned above while also CC:ing the
49maintainers mentioned in the README file. Use the same rule for adding a
50subject prefix as above and method for sending the patch.
51
52If the changes are backward incompatible changes to an unstable protocol,
53see <<Unstable protocol changes>>.
54
55Interface naming convention
56~~~~~~~~~~~~~~~~~~~~~~~~~~~
57All protocols should avoid using generic namespaces or no namespaces in
58the protocol interface names in order to minimize risk that the generated
59C API collides with other C API. Interface names that may collide with
60interface names from other protocols should also be avoided.
61
62For generic protocols not limited to certain configurations (such as
63specific desktop environment or operating system) the +wp_+ prefix
64should be used on all interfaces in the protocol.
65
66For operating system specific protocols, the interfaces should be
67prefixed with both +wp_+ and the operating system, for example
68+wp_linux_+, or +wp_freebsd_+, etc.
69
70Unstable naming convention
71~~~~~~~~~~~~~~~~~~~~~~~~~~
72Unstable protocols have a special naming convention in order to make it
73possible to make discoverable backward incompatible changes.
74
75An unstable protocol has at least two versions: the major version, which
76represents backward incompatible changes, and the minor version, which
77represents backward compatible changes to the interfaces in the protocol.
78
79The major version is part of the XML file name, the protocol name in the
80XML, and interface names in the protocol.
81
82Minor versions are the version attributes of the interfaces in the XML.
83There may be more than one minor version per protocol, if there are more
84than one global.
85
86The XML file and protocol name also has the word 'unstable' in them, and
87all of the interfaces in the protocol are prefixed with +z+ and
88suffixed with the major version number.
89
90For example, an unstable protocol called foo-bar with major version 2
91containing the two interfaces wp_foo and wp_bar both minor version 1 will
92be placed in the directory +unstable/foo-bar/+ consisting of one file
93called +README+ and one called +foo-bar-unstable-v2.xml+. The XML file
94will consist of two interfaces called +zwp_foo_v2+ and +zwp_bar_v2+ with
95the +version+ attribute set to +1+.
96
97Unstable protocol changes
98~~~~~~~~~~~~~~~~~~~~~~~~~
99During the development of a new protocol it is possible that backward
100incompatible changes are needed. Such a change needs to be represented
101in the major and minor versions of the protocol.
102
103Assuming a backward incompatible change is needed, the procedure for how to
104do so is the following:
105
106  . Make a copy of the XML file with the major version increased by +1+.
107  . Increase the major version number in the protocol XML by +1+.
108  . Increase the major version number in all of the interfaces in the
109    XML by +1+.
110  . Reset the minor version number (interface version attribute) of all
111    the interfaces to +1+.
112
113Backward compatible changes within a major unstable version can be done
114in the regular way as done in core Wayland or in stable protocols.
115
116Declaring a protocol stable
117~~~~~~~~~~~~~~~~~~~~~~~~~~~
118Once it is decided that a protocol should be declared stable, meaning no
119more backward incompatible changes will ever be allowed, one last
120breakage is needed.
121
122The procedure of doing this is the following:
123
124  . Create a new directory in the +stable/+ toplevel directory with the
125    same name as the protocol directory in the +unstable/+ directory.
126  . Copy the final version of the XML that is the version that was
127    decided to be declared stable into the new directory. The target name
128    should be the same name as the protocol directory but with the +.xml+
129    suffix.
130  . Rename the name of the protocol in the XML by removing the
131    'unstable' part and the major version number.
132  . Remove the +z+ prefix and the major version number suffix from all
133    of the interfaces in the protocol.
134  . Reset all of the interface version attributes to +1+.
135  . Update the +README+ file in the unstable directory and create a new
136    +README+ file in the new directory.
137
138Releases
139~~~~~~~~
140Each release of wayland-protocols finalizes the version of the protocols
141to their state they had at that time.
142