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 phases 14 15Protocols in general has three phases: the development phase, the testing 16phase, and the stable phase. 17 18In the development phase, a protocol is not officially part of 19wayland-protocols, but is actively being developed, for example by 20iterating over it in a 21[merge 22request](https://gitlab.freedesktop.org/wayland/wayland-protocols/merge_requests), 23or planning it in an 24[issue](https://gitlab.freedesktop.org/wayland/wayland-protocols/issues). 25 26During this phase, patches for clients and compositors are written as a test 27vehicle. Such patches must not be merged in clients and compositors, because 28the protocol can still change. 29 30When a protocol has reached a stage where it is ready for wider adoption, 31and after the [GOVERNANCE section 322.3](GOVERNANCE.md#2.3-introducing-new-protocols) requirements have been 33met, it enters the "testing" phase. At this point, the protocol is added 34to `staging/` directory of wayland-protocols and made part of a release. 35What this means is that implementation is encouraged in clients and 36compositors where the functionality it specifies is wanted. 37 38Extensions in staging cannot have backward incompatible changes, in that 39sense they are equal to stable extensions. However, they may be completely 40replaced with a new major version, or a different protocol extension all 41together, if design flaws are found in the testing phase. 42 43After a staging protocol has been sufficiently tested in the wild and 44proven adequate, its maintainers and the community at large may declare it 45"stable", meaning it is unexpected to become superseded by a new major 46version. 47 48## Deprecation 49 50A protocol may be deprecated, if it has been replaced by some other 51protocol, or declared undesirable for some other reason. No more changes 52will be made to a deprecated protocol. 53 54## Legacy protocol phases 55 56An "unstable" protocol refers to a protocol categorization policy 57previously used by wayland-protocols, where protocols initially 58placed in the `unstable/` directory had certain naming conventions were 59applied, requiring a backward incompatible change to be declared "stable". 60 61During this phase, protocol extension interface names were in addition to 62the major version postfix also prefixed with `z` to distinguish from 63stable protocols. 64 65## Protocol directory tree structure 66 67Depending on which stage a protocol is in, the protocol is placed within 68the toplevel directory containing the protocols with the same stage. 69Stable protocols are placed in the `stable/` directory, staging protocols 70are placed in the `staging/` directory, and deprecated protocols are 71placed in the `deprecated/` directory. 72 73Unstable protocols (see [Legacy protocol phases](#legacy-protocol-phases)) 74can be found in the `unstable/` directory, but new ones should never be 75placed here. 76 77## Protocol development procedure 78 79To propose a new protocol, create a GitLab merge request adding the 80relevant files and Makefile.am entry to the repository with the 81explanation and motivation in the commit message. Protocols are 82organized in namespaces describing their scope ("wp", "xdg" and "ext"). 83There are different requirements for each namespace, see [GOVERNANCE 84section 2](GOVERNANCE.md#2-protocols) for more information. 85 86If the new protocol is just an idea, open an issue on the GitLab issue 87tracker. If the protocol isn't ready for complete review yet and is an 88RFC, create a merge request and add the "WIP:" prefix in the title. 89 90To propose changes to existing protocols, create a GitLab merge request. 91 92Please include a `Signed-off-by` line at the end of the commit to certify 93that you wrote it or otherwise have the right to pass it on as an 94open-source patch. See the 95[Developer Certificate of Origin](https://developercertificate.org/) for 96a formal definition. 97 98## Interface naming convention 99 100All protocols should avoid using generic namespaces or no namespaces in 101the protocol interface names in order to minimize risk that the generated 102C API collides with other C API. Interface names that may collide with 103interface names from other protocols should also be avoided. 104 105For generic protocols not limited to certain configurations (such as 106specific desktop environment or operating system) the `wp_` prefix 107should be used on all interfaces in the protocol. 108 109For protocols allowing clients to configure how their windows are 110managed, the `xdg_` prefix should be used. 111 112For operating system specific protocols, the interfaces should be 113prefixed with both `wp_` and the operating system, for example 114`wp_linux_`, or `wp_freebsd_`, etc. 115 116For more information about namespaces, see [GOVERNANCE section 2.1 117](GOVERNANCE.md#21-protocol-namespaces). 118 119Each new protocol XML file must include a major version postfix, starting 120with `-v1`. The purpose of this postfix is to make it possible to 121distinguish between backward incompatible major versions of the same 122protocol. 123 124The interfaces in the protocol XML file should as well have the same 125major version postfix in their names. 126 127For example, the protocol `foo-bar` may have a XML file 128`foo-bar/foo-bar-v1.xml`, consisting of the interface `wp_foo_bar_v1`, 129corresponding to the major version 1, as well as the newer version 130`foo-bar/foo-bar-v2.xml` consisting of the interface `wp_foo_bar_v2`, 131corresponding to the major version 2. 132 133## Include a disclaimer 134 135Include the following disclaimer: 136 137``` 138Warning! The protocol described in this file is currently in the testing 139phase. Backward compatible changes may be added together with the 140corresponding interface version bump. Backward incompatible changes can 141only be done by creating a new major version of the extension. 142``` 143 144## Backward compatible protocol changes 145 146A protocol may receive backward compatible additions and changes. This 147is to be done in the general Wayland way, using `version` and `since` XML 148element attributes. 149 150## Backward incompatible protocol changes 151 152While not preferred, a protocol may at any stage, especially during the 153testing phase, when it is located in the `staging/` directory, see 154backward incompatible changes. 155 156Assuming a backward incompatible change is needed, the procedure for how to 157do so is the following: 158 159- Make a copy of the XML file with the major version increased by 1. 160- Increase the major version number in the protocol XML by 1. 161- Increase the major version number in all of the interfaces in the 162 XML by 1. 163- Reset the interface version number (interface version attribute) of all 164 the interfaces to 1. 165- Remove all of the `since` attributes. 166 167## Declaring a protocol stable 168 169Once it has been concluded that a protocol been proven adequate in 170production, and that it is deemed unlikely to receive any backward 171incompatible changes, it may be declared stable. 172 173The procedure of doing this is the following: 174 175- Create a new directory in the `stable/` toplevel directory with the 176 same name as the protocol directory in the `staging/` directory. 177- Copy the final version of the XML that is the version that was 178 decided to be declared stable into the new directory. The target name 179 should be the same name as the protocol directory but with the `.xml` 180 suffix. 181- Remove the disclaimer about the protocol being in the testing phase. 182- Update the `README` file in the staging directory and create a new 183 `README` file in the new directory. 184- Replace the disclaimer in the protocol files left in the staging/ 185 directory with the following: 186 187``` 188Disclaimer: This protocol extension has been marked stable. This copy is 189no longer used and only retained for backwards compatibility. The 190canonical version can be found in the stable/ directory. 191``` 192 193Note that the major version of the stable protocol extension, as well as 194all the interface versions and names, must remain unchanged. 195 196There are other requirements for declaring a protocol stable, see 197[GOVERNANCE section 2.3](GOVERNANCE.md#23-introducing-new-protocols). 198 199## Releases 200 201Each release of wayland-protocols finalizes the version of the protocols 202to their state they had at that time. 203 204## Gitlab conventions 205 206### Triaging merge requests 207 208New merge requests should be triaged. Doing so requires the one doing the 209triage to add a set of initial labels: 210 211~"New Protocol" - For a new protocol being added. If it's an amendment to 212an existing protocol, apply the label of the corresponding protocol 213instead. If none exist, create it. 214 215~"Needs acks" - If the protocol needs one or more acknowledgements. 216 217~"Needs implementations" - If there are not enough implementations of the 218protocol. 219 220~"Needs review" - If the protocol is in need of review. 221 222~"In 30 day discussion period" - If the protocol needs a 30 day discussion 223period. 224 225For the meaning and requirement of acknowledgments and available 226implementations, see the GOVERNANCE.md document. 227 228### Managing merge requests 229 230When merge requests get their needed feedback and items, remove the 231corresponding label that marks it as needing something. For example, if a 232merge request receives all the required acknowledgments, remove the 233~"Needs acks" label, or if 30 days passed since opening, remove any 234~"In 30 day discussion period" label. 235 236### Nacking a merge request 237 238If the inclusion of a merge request is denied due to one or more Nacks, add 239the ~Nacked label. 240