Protocol backwards compatibility requirements?

Simon Ser contact at
Wed Apr 15 14:27:26 UTC 2020


On Monday, April 13, 2020 1:59 AM, Peter Hutterer <peter.hutterer at> wrote:
> Hi all,
> This is request for comments on the exact requirements for protocol
> backwards compatibility for clients binding to new versions of an interface.
> Reason for this are the high-resolution wheel scrolling patches:
> Specifically, the question is: do we **change** protocol elements or
> behaviour as the interface versions increase? A few random examples:

What we can't do is:

- Change existing messages' signature
- Completely remove a message

> - event introduced in version N sends a wl_fixed in
>   surface coordinates. version N+1 changes this to a normalized
>   [-10000, +10000] range.

Argument types can't be changed. This would be a breaking change for the
generated code, we can't do that.

> - request introduced in version N takes an int. version N+1
>   changes to take a wl_fixed and an enum.


> - request introduced in version N guaranteed to generate a single
>   event wl_foo.baz. if the client binds to version N+1 that event may be
>   sent zero, one or multiple times.

This is fine.

> I think these examples cover a wide-enough range of the possible changes.
> My assumption was that we only ever add new requests/events but never change
> existing behaviour. So introduced in version N will always have
> the same behaviour for any interface N+m.

We can change existing requests' behaviour. This has already been done a
number of times, see e.g. wl_data_offer.accept or xdg_output.description.

Clients should always have a max-version, ie. they should never blindly bind
to the compositor's version.

What is also fine is marking a message as "deprecated from version N". Such a
message wouldn't be sent anymore starting from this version.

> I've seen some pushback for above linked patchset because it gets
> complicated and suggestions to just change the current interface.
> The obvious advantage is being able to clean up any mess in the protocol.
> The disadvantages are the breakage of backwards compatibility with older
> versions. You're effectively forcing every compositor/client to change the
> code based on the version number, even where it's not actually needed. Or,
> IOW, a client may want a new feature in N+2 but now needs to implement all
> changes from N+1 since they may change the behaviour significantly.


More information about the wayland-devel mailing list