Protocol backwards compatibility requirements?

[Christopher James Halse Rogers]

On Wed, Apr 15, 2020 at 14:27, Simon Ser <contact at emersion.fr> wrote:
> 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

It should be relatively easy to modify wayland-scanner to support both 
of these things, *if* we decide that it's a reasonable thing to do. 
(You'd do something like add support for <request name="foo" 
removed_in="5"/> and the like)

> 
>>  - 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.

But this isn't changing the argument type; it's changing the 
interpretation of the argument.
In both cases the type is wl_fixed; in the first you interpret this 
wl_fixed as being in surface coordinates, in the second you interpret 
it differently.

This doesn't require any changes to code generation; I don't think this 
is (in principle) any more disruptive than changing “wl_foo.baz is 
sent exactly once” to “wl_foo.baz is sent zero or more times”, 
which you're happy with.

> 
>>  - 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.
> 

This is the meat of the question - all of the changes described are 
technically fairly simple to implement.

To some extent this is a question of self-limitations. As has been 
mentioned, protocols have *already* been deliberately broken in this 
way, and people are happy enough with that. As long as we're mindful of 
the cost such changes impose, I think that having the technical 
capability to make such changes is of benefit - for example, rather 
than marking a message as “deprecated from version N” I think it 
would be preferable to just not have the message in the listener 
struct. (Note that I'm not volunteering to *implement* that capability, 
and there are probably more valuable things to work on, but if it 
magically appeared without any effort it'd be nice to have that 
capability).

The status quo is that we're happy (perhaps accidentally) with 
requiring a client to implement all changes from N+1 in order to get 
something from N+2. I think whether or not that's ok is a case-by-case 
decision. How difficult is it for clients to implement N+1? How much 
simpler does the break make protocol version N+1? If it's trivial for 
clients to handle and makes the protocol significantly simpler, I think 
it's obvious that we *should* make the break; likewise, if it's likely 
to be difficult for clients to handle and doesn't make N+1 much 
simpler, it's obvious that we *shouldn't*.

For the specific case at hand, it doesn't seem like it would be 
particularly difficult for clients to handle axis events changing 
meaning in version 8, and it looks like the protocol would be 
substantially simpler without the interaction between axis_v120, axis, 
and axis_discrete.