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