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 <paul.tvete@qt.io>

1 files changed, 18 insertions, 0 deletions

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.