Protocol backwards compatibility requirements?

[Simon Ser]

Hi,

On Monday, April 13, 2020 1:59 AM, Peter Hutterer <peter.hutterer at who-t.net> 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:
> https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/72
>
> 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 wl_foo.bar 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 wl_foo.bar introduced in version N takes an int. version N+1
>   changes wl_foo.bar to take a wl_fixed and an enum.

Ditto.

> - request wl_foo.bar 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 wl_foo.bar 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.

Indeed.