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