Protocol backwards compatibility requirements?

[Peter Hutterer]

On Thu, Apr 16, 2020 at 05:47:56PM +1000, Christopher James Halse Rogers wrote:
> 
> 
> 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.

yes, I agree, this is more a "political" choice or as you say, a question of
what do we limit ourselves to.
 
> 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).

I'd even argue that the hard-breaking changes are safer since they
definitely throw up warnings and/or break compilation, whereas the subtle
behaviour changes will quietly fly under the radar. e.g. the value range
change (which, not coincidentally, is what we're talking about here).

But yeah, it still comes down to "what are we happy with" which, ideally is
some sort of consensus.
 
> 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.

At least the protocol will be substantially simpler, yes :)

Cheers,
   Peter