From d1a8677d72ba3d205263d8578a42ea1695245d04 Mon Sep 17 00:00:00 2001 From: Johan Klokkhammer Helsing Date: Wed, 23 May 2018 14:30:13 +0200 Subject: Add readme for internal protocol extension folder There have been some misunderstandings about the compatibility guarantees of our internal protocols. I.e. some compositors have started implementing them, and then we have removed or made backwards incompatible changes to the protocols. Also, when we've made backwards incompatible changes, we've previously incorrectly used the version attribute of the interface, however that attribute is supposed to be used for backwards *compatible* changes. This causes problems for both ourselves and others. So let's be explicit about it in a README and be more careful when reviewing protocol extension changes if they don't bump the version suffix (i.e. rename the protocol). This is the same versioning and naming scheme as used by the unstable protocols in wayland-protocols. Task-number QTBUG-68423 Change-Id: I9c1a7e13c9356660914bbfeff4139ec033f1d443 Reviewed-by: Paul Olav Tvete --- src/extensions/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 src/extensions/README.md (limited to 'src/extensions') diff --git a/src/extensions/README.md b/src/extensions/README.md new file mode 100644 index 000000000..f75e0f236 --- /dev/null +++ b/src/extensions/README.md @@ -0,0 +1,18 @@ +# Internal Qt protocol extensions + +The protocol extensions in this folder are considered implementation details of +Qt. I.e. they may removed, renamed or changed without warning. + +## Suffixed protocols + +For protocols that have a version suffix, however, we will strive to not break +backwards compatibility without bumping the suffix (renaming the protocol). +E.g.: If your client sees a `zqt_key_v1` global, it can safely bind to it: +the key event will always take the same number of arguments, regardless of +compositor version. + +This is important also within a Qt-only scope if there are multiple versions of +Qt on the system. Consider for instance an application statically linked to Qt +(such as Qt Creator) running against a Qt compositor installed by the distro). +In such cases we don't want the compositor and client to disagree on the +protocol definition. -- cgit v1.2.3