From 7f21a684f7fc98a687cda207175b900aec7e551e Mon Sep 17 00:00:00 2001 From: Paul Olav Tvete Date: Thu, 28 Feb 2019 10:23:16 +0100 Subject: [PATCH] Guarantee compatibility for Qt's extension protocols Spell out and formalize the policy that we have been following since Qt 5.4: We don't break compatibility for our internal protocols. Otherwise, it would not be safe to use a Qt client with a Qt-based compositor. Change-Id: I632e9fbb56095ab07560413977c79777ae9fdcd2 Reviewed-by: Johan Helsing Reviewed-by: Pier Luigi Fiorini --- src/3rdparty/wayland/extensions/README.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/3rdparty/wayland/extensions/README.md b/src/3rdparty/wayland/extensions/README.md index f75e0f23665..8024ffa80e7 100644 --- a/src/3rdparty/wayland/extensions/README.md +++ b/src/3rdparty/wayland/extensions/README.md @@ -3,12 +3,10 @@ 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 +However, starting with Qt 5.4, we promise not to break backwards compatibility +without renaming (or removing) the protocol. I.e., if your client sees a global +from one of these extensions, it can safely bind to it: the existing events +and requests 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 @@ -16,3 +14,11 @@ 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. + +## Protocol versioning. + +Protocol extensions in this folder should be versioned (e.g. `zqt_key_v1`). +If it is necessary to break protocol compatibility, they will be renamed by +incrementing the version number. For legacy reasons, there are also unversioned +protocols in this folder. Those protocols should be renamed to be versioned +if compatibility is broken.