README
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
README.md
1# Wayland protocols
2
3wayland-protocols contains Wayland protocols that add functionality not
4available in the Wayland core protocol. Such protocols either add
5completely new functionality, or extend the functionality of some other
6protocol either in Wayland core, or some other protocol in
7wayland-protocols.
8
9A protocol in wayland-protocols consists of a directory containing a set
10of XML files containing the protocol specification, and a README file
11containing detailed state and a list of maintainers.
12
13## Protocol directory tree structure
14
15Protocols may be "stable", "unstable" or "deprecated", and the interface
16and protocol names as well as place in the directory tree will reflect
17this.
18
19A stable protocol is a protocol which has been declared stable by
20the maintainers. Changes to such protocols will always be backward
21compatible.
22
23An unstable protocol is a protocol currently under development and this
24will be reflected in the protocol and interface names. See [Unstable
25naming convention](#unstable-naming-convention).
26
27A deprecated protocol is a protocol that has either been replaced by some
28other protocol, or declared undesirable for some other reason. No more
29changes will be made to a deprecated protocol.
30
31Depending on which of the above states the protocol is in, the protocol
32is placed within the toplevel directory containing the protocols with the
33same state. Stable protocols are placed in the `stable/` directory,
34unstable protocols are placed in the `unstable/` directory, and
35deprecated protocols are placed in the `deprecated/` directory.
36
37## Protocol development procedure
38
39To propose a new protocol, create a GitLab merge request adding the
40relevant files and Makefile.am entry to the repository with the
41explanation and motivation in the commit message. Protocols are
42organized in namespaces describing their scope ("wp", "xdg" and "ext").
43There are different requirements for each namespace, see [GOVERNANCE
44section 2](GOVERNANCE.md#2-protocols) for more information.
45
46If the new protocol is just an idea, open an issue on the GitLab issue
47tracker. If the protocol isn't ready for complete review yet and is an
48RFC, create a merge request and add the "WIP:" prefix in the title.
49
50To propose changes to existing protocols, create a GitLab merge request.
51
52If the changes are backward incompatible changes to an unstable protocol,
53see [Unstable protocol changes](#unstable-protocol-changes).
54
55## Interface 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 protocols allowing clients to configure how their windows are
67managed, the `xdg_` prefix should be used.
68
69For operating system specific protocols, the interfaces should be
70prefixed with both `wp_` and the operating system, for example
71`wp_linux_`, or `wp_freebsd_`, etc.
72
73For more information about namespaces, see [GOVERNANCE section 2.1
74](GOVERNANCE.md#21-protocol-namespaces).
75
76## Unstable naming convention
77
78Unstable protocols have a special naming convention in order to make it
79possible to make discoverable backward incompatible changes.
80
81An unstable protocol has at least two versions: the major version, which
82represents backward incompatible changes, and the minor version, which
83represents backward compatible changes to the interfaces in the protocol.
84
85The major version is part of the XML file name, the protocol name in the
86XML, and interface names in the protocol.
87
88Minor versions are the version attributes of the interfaces in the XML.
89There may be more than one minor version per protocol, if there are more
90than one global.
91
92The XML file and protocol name also has the word 'unstable' in them, and
93all of the interfaces in the protocol are prefixed with `z` and
94suffixed with the major version number.
95
96For example, an unstable protocol called `foo-bar` with major version 2
97containing the two interfaces `wp_foo` and `wp_bar` both minor version 1
98will be placed in the directory `unstable/foo-bar/` consisting of one file
99called `README` and one called `foo-bar-unstable-v2.xml`. The XML file
100will consist of two interfaces called `zwp_foo_v2` and `zwp_bar_v2` with
101the `version` attribute set to 1.
102
103## Unstable protocol changes
104
105During the development of a new protocol it is possible that backward
106incompatible changes are needed. Such a change needs to be represented
107in the major and minor versions of the protocol.
108
109Assuming a backward incompatible change is needed, the procedure for how to
110do so is the following:
111
112- Make a copy of the XML file with the major version increased by 1.
113- Increase the major version number in the protocol XML by 1.
114- Increase the major version number in all of the interfaces in the
115 XML by 1.
116- Reset the minor version number (interface version attribute) of all
117 the interfaces to 1.
118
119Backward compatible changes within a major unstable version can be done
120in the regular way as done in core Wayland or in stable protocols.
121
122## Declaring a protocol stable
123
124Once it is decided that a protocol should be declared stable, meaning no
125more backward incompatible changes will ever be allowed, one last
126breakage is needed.
127
128The procedure of doing this is the following:
129
130- Create a new directory in the `stable/` toplevel directory with the
131 same name as the protocol directory in the `unstable/` directory.
132- Copy the final version of the XML that is the version that was
133 decided to be declared stable into the new directory. The target name
134 should be the same name as the protocol directory but with the `.xml`
135 suffix.
136- Rename the name of the protocol in the XML by removing the
137 `unstable` part and the major version number.
138- Remove the `z` prefix and the major version number suffix from all
139 of the interfaces in the protocol.
140- Reset all of the interface version attributes to 1.
141- Update the `README` file in the unstable directory and create a new
142 `README` file in the new directory.
143
144There are other requirements for declaring a protocol stable, see
145[GOVERNANCE section 2.3](GOVERNANCE.md#23-introducing-new-protocols).
146
147## Releases
148
149Each release of wayland-protocols finalizes the version of the protocols
150to their state they had at that time.
151
152## Gitlab conventions
153
154### Triaging merge requests
155
156New merge requests should be triaged. Doing so requires the one doing the
157triage to add a set of initial labels:
158
159~"New Protocol" - For a new protocol being added. If it's an amendment to
160an existing protocol, apply the label of the corresponding protocol
161instead. If none exist, create it.
162
163~"Needs acks" - If the protocol needs one or more acknowledgements.
164
165~"Needs implementations" - If there are not enough implementations of the
166protocol.
167
168~"Needs review" - If the protocol is in need of review.
169
170~"In 30 day discussion period" - If the protocol needs a 30 day discussion
171period.
172
173For the meaning and requirement of acknowledgments and available
174implementations, see the GOVERNANCE.md document.
175
176### Managing merge requests
177
178When merge requests get their needed feedback and items, remove the
179corresponding label that marks it as needing something. For example, if a
180merge request receives all the required acknowledgments, remove the ~"Needs
181acks" label, or if 30 days passed since opening, remove any ~"In 30 days
182discussion period" label.
183
184### Nacking a merge request
185
186If the inclusion of a merge request is denied due to one or more Nacks, add
187the ~Nacked label.
188