Re: Protocol backwards compatibility requirements?
On Tue, Apr 21, 2020 at 11:50:27AM +0300, Pekka Paalanen wrote: [...] > > > If you're asking if the implementation for version < N could be > > > deleted or avoided, then I'd say no. Definitely no for desktop > > > compositors, probably no for anything else public. > > > > The sub-interfaces are inseparable from the seats, that's set in stone. The > > question here is less about mixing versions within the seat but more > > about skipping versions without harm. Let's say wl_pointer version 9 > > introduces wl_pointer.pressure, something independent of anything else > > else in the wl_pointer interface. Qt (iirc) never implemented axis_discrete > > handling but it let's say it wants support for pressure. > > > > Guaranteed backwards compatibility means Qt can bump to version 9, implement > > noop functions for axis_source and axis_discrete and done. > > > > Allowing events to change between versions means that Qt now also needs to > > update its handling of whatever changed between those versions, e.g. > > wl_pointer.axis. A direct jump past versions you don't care about isn't > > possible. > > I would say that the direct jump past versions is never possible. Like > you said, Qt still needs to implement the noop functions. If it > doesn't, it will crash when those events get sent. The fact that making > those new functions noop is ok is just a detail, an accident of design. > Qt must come with a valid implementation - what a valid and workable > implementation is, is just a detail. > > > Also, having written the patches to change wl_pointer.axis_discrete to a 120 > > base value there's another issue: no auto-generated FOO_SINCE_VERSION > > because this doesn't show up in the protocol itself. So this really flies > > under the radar and you just have to know about it by reading the > > documentation. > > Was that one of the breaking changes already done in the past? so, checking the two examples Simon mentioned: - wl_data_offer.accept: semantics changed from "yes, I can receive this type" to "I have received and processed this type and I'm done now". - xdg_output.description: event was only sent once, changed to sent multiple times. Notable: xdg_output is still officially unstable anyway. So a change in message semantics and how often a message can be received but not in the actual data delivered. Not directly comparable to a potential change in the value ranges of an event. > Sounds to me like it's just one more reason to not change existing > message semantics, and add new messages instead. > > Maybe one possibility with e.g. wl_pointer, if you actually want to > shed the old cruft, is to create interface wl_pointer2 and add > get_pointer2 request to wl_seat. We will never be able to get rid of > the original wl_pointer interface or its implementations, but at least > it would be clearly separate. Good point, but I don't think it's worth it. For something that's moving more frequently this may help, but I don't anticipate a lot of wl_pointer changes. So this would require double the boilerplate everywhere whith very little benefit. Cheers, Peter ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: Protocol backwards compatibility requirements?
On 21/04/20 12:57 pm, Christopher James Halse Rogers wrote: On Mon, Apr 20, 2020 at 15:05, Pekka Paalanen wrote: On Thu, 16 Apr 2020 17:47:56 +1000 Christopher James Halse Rogers wrote: On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: > Hi, > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > 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 Indeed. 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 and the like) How would that work, given the version is negotiated at runtime? The message signature structs are now ABI as well, and we have no room for alternate signatures, do we? Sure we do. Internally we can just give them different names, with different contents, and switch based on the version requested at runtime. From the client API side it's more difficult (at least for requests), because we can't remove any symbols - we *can* make it a client error with a good error message, though. On the events side it's easier, as we can add a wl_foo_listener_v5 struct and wl_foo_add_listener_v5. This does add a new sharp edge to the raw wl_proxy_* interface, but client code isn't expected to be using that and this doesn't seem particularly hard for language bindings to adapt to. There is more than just libwayland and wayland-scanner for C that needs to be taken into consideration here. Adding any of these kinds of changes requires that _everybody_ updates to handle this, including things like the Rust Wayland binding/reimplementation and Qt's own Wayland scanner. I really don't think it's worth the effort. Scott ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: Protocol backwards compatibility requirements?
On Tue, 21 Apr 2020 10:57:34 +1000 Christopher James Halse Rogers wrote: > On Mon, Apr 20, 2020 at 15:05, Pekka Paalanen > wrote: > > On Thu, 16 Apr 2020 17:47:56 +1000 > > Christopher James Halse Rogers wrote: > > > >> On Wed, Apr 15, 2020 at 14:27, Simon Ser > >> wrote: > >> > Hi, > >> > > >> > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > >> > 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 > > > > Indeed. > > > >> > >> 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 >> removed_in="5"/> and the like) > > > > How would that work, given the version is negotiated at runtime? > > > > The message signature structs are now ABI as well, and we have no room > > for alternate signatures, do we? > > Sure we do. Internally we can just give them different names, with > different contents, and switch based on the version requested at > runtime. > > From the client API side it's more difficult (at least for requests), > because we can't remove any symbols - we *can* make it a client error > with a good error message, though. > > On the events side it's easier, as we can add a wl_foo_listener_v5 > struct and wl_foo_add_listener_v5. > > This does add a new sharp edge to the raw wl_proxy_* interface, but > client code isn't expected to be using that and this doesn't seem > particularly hard for language bindings to adapt to. I guess I'd have to see all that implemented to see how it would work. It's too far a stretch for my imagination atm. What I can imagine is that it will lead to a lot of boilerplate code to use different types with different object versions at runtime when you cannot require a minimum negotiated version greater than 1. > > Something we rarely consider is if you pass Wayland protocol objects > > into a library without negotiating the object version with the library > > first. For example, we pass wl_surface into the EGL Wayland wrapper > > library. If wl_surface would get a version bump breaking backwards > > compatibility, meaning that version N+1 changes something that existed > > in version N, the library handling only version N would fall apart. > > > > I sincerely hope this is the only case of a library taking a > > ready-made > > Wayland object in. Getting the version negotiation right needs > > inconvenient additions to the library API that I don't think many > > would > > bother or even realize it's needed. > > > > You can query the version of a wl_proxy, sure, but that does not help > > you if it returns a number larger than what your code knows about. > > > > Btw. this is also a problem in the opposite direction. Let's say you > > use a toolkit and the toolkit allows you access to the Wayland > > protocol > > objects. Then the toolkit gains support for new interface versions and > > uses them, but your app code is not updated. If the protocol change is > > backwards incompatible, your app code may break even if only behaviour > > changes and not signatures. > > This is an additional cost that should be considered for types that may > be transferred across library boundaries like this; we should also try > to make it clear to toolkits that this is a fraught API. Sure. How? By who? > >> This is the meat of the question - all of the changes described are > >> technically fairly simple to implement. > > > > Breaking stuff is simple, sure. Or what do you mean? > > Making breaking changes to version N+1 of a protocol in a way that > preserves the ability for version 1…N clients to continue to function > unchanged is technically fairly simple. The question is when we > *should*, and how much effort we should invest in capitalising on such > changes. Do you make some assumptions about the problem I described when passing protocol objects between independent components/libraries? Like that the problem does not exist? Or that it's ok to disconnect if the object version is not at least N+1? > >> 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 > >>
Re: Protocol backwards compatibility requirements?
On Tue, 21 Apr 2020 15:01:14 +1000 Peter Hutterer wrote: > On Mon, Apr 20, 2020 at 03:05:32PM +0300, Pekka Paalanen wrote: > > On Thu, 16 Apr 2020 17:47:56 +1000 > > Christopher James Halse Rogers wrote: > > > > > On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: > > > > Hi, > > > > > > > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > > > > 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 > > > > Indeed. ... > > If you're asking if the implementation for version < N could be > > deleted or avoided, then I'd say no. Definitely no for desktop > > compositors, probably no for anything else public. > > The sub-interfaces are inseparable from the seats, that's set in stone. The > question here is less about mixing versions within the seat but more > about skipping versions without harm. Let's say wl_pointer version 9 > introduces wl_pointer.pressure, something independent of anything else > else in the wl_pointer interface. Qt (iirc) never implemented axis_discrete > handling but it let's say it wants support for pressure. > > Guaranteed backwards compatibility means Qt can bump to version 9, implement > noop functions for axis_source and axis_discrete and done. > > Allowing events to change between versions means that Qt now also needs to > update its handling of whatever changed between those versions, e.g. > wl_pointer.axis. A direct jump past versions you don't care about isn't > possible. I would say that the direct jump past versions is never possible. Like you said, Qt still needs to implement the noop functions. If it doesn't, it will crash when those events get sent. The fact that making those new functions noop is ok is just a detail, an accident of design. Qt must come with a valid implementation - what a valid and workable implementation is, is just a detail. > Also, having written the patches to change wl_pointer.axis_discrete to a 120 > base value there's another issue: no auto-generated FOO_SINCE_VERSION > because this doesn't show up in the protocol itself. So this really flies > under the radar and you just have to know about it by reading the > documentation. Was that one of the breaking changes already done in the past? Sounds to me like it's just one more reason to not change existing message semantics, and add new messages instead. Maybe one possibility with e.g. wl_pointer, if you actually want to shed the old cruft, is to create interface wl_pointer2 and add get_pointer2 request to wl_seat. We will never be able to get rid of the original wl_pointer interface or its implementations, but at least it would be clearly separate. Thanks, pq pgpUcHDO4KBbz.pgp Description: OpenPGP digital signature ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: Protocol backwards compatibility requirements?
On Mon, Apr 20, 2020 at 03:05:32PM +0300, Pekka Paalanen wrote: > On Thu, 16 Apr 2020 17:47:56 +1000 > Christopher James Halse Rogers wrote: > > > On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: > > > Hi, > > > > > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > > > 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 > > Indeed. > > > > > 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 > removed_in="5"/> and the like) > > How would that work, given the version is negotiated at runtime? > > The message signature structs are now ABI as well, and we have no room > for alternate signatures, do we? > > > > > > >> - event wl_foo.bar introduced in version N sends a wl_fixed in > > >>surface coordinates. version N+1 changes this to a normalized > > >>[-1, +1] 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. > > Something we rarely consider is if you pass Wayland protocol objects > into a library without negotiating the object version with the library > first. For example, we pass wl_surface into the EGL Wayland wrapper > library. If wl_surface would get a version bump breaking backwards > compatibility, meaning that version N+1 changes something that existed > in version N, the library handling only version N would fall apart. ftr, this seems like something that should be noted in the protocol's xml directly to avoid future accidents. > I sincerely hope this is the only case of a library taking a ready-made > Wayland object in. Getting the version negotiation right needs > inconvenient additions to the library API that I don't think many would > bother or even realize it's needed. > > You can query the version of a wl_proxy, sure, but that does not help > you if it returns a number larger than what your code knows about. > > Btw. this is also a problem in the opposite direction. Let's say you > use a toolkit and the toolkit allows you access to the Wayland protocol > objects. Then the toolkit gains support for new interface versions and > uses them, but your app code is not updated. If the protocol change is > backwards incompatible, your app code may break even if only behaviour > changes and not signatures. > > > >> - 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
Re: Protocol backwards compatibility requirements?
On Mon, Apr 20, 2020 at 15:05, Pekka Paalanen wrote: On Thu, 16 Apr 2020 17:47:56 +1000 Christopher James Halse Rogers wrote: On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: > Hi, > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > 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 Indeed. 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 and the like) How would that work, given the version is negotiated at runtime? The message signature structs are now ABI as well, and we have no room for alternate signatures, do we? Sure we do. Internally we can just give them different names, with different contents, and switch based on the version requested at runtime. From the client API side it's more difficult (at least for requests), because we can't remove any symbols - we *can* make it a client error with a good error message, though. On the events side it's easier, as we can add a wl_foo_listener_v5 struct and wl_foo_add_listener_v5. This does add a new sharp edge to the raw wl_proxy_* interface, but client code isn't expected to be using that and this doesn't seem particularly hard for language bindings to adapt to. > >> - event wl_foo.bar introduced in version N sends a wl_fixed in >>surface coordinates. version N+1 changes this to a normalized >>[-1, +1] 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. Something we rarely consider is if you pass Wayland protocol objects into a library without negotiating the object version with the library first. For example, we pass wl_surface into the EGL Wayland wrapper library. If wl_surface would get a version bump breaking backwards compatibility, meaning that version N+1 changes something that existed in version N, the library handling only version N would fall apart. I sincerely hope this is the only case of a library taking a ready-made Wayland object in. Getting the version negotiation right needs inconvenient additions to the library API that I don't think many would bother or even realize it's needed. You can query the version of a wl_proxy, sure, but that does not help you if it returns a number larger than what your code knows about. Btw. this is also a problem in the opposite direction. Let's say you use a toolkit and the toolkit allows you access to the Wayland protocol objects. Then the toolkit gains support for new interface versions and uses them, but your app code is not updated. If the protocol change is backwards incompatible, your app code may break even if only behaviour changes and not signatures. This is an additional cost that should be considered for types that may be transferred across library boundaries like this; we should also try to make it clear to toolkits that this is a fraught API. >> - 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
Re: Protocol backwards compatibility requirements?
On Mon, 2020-04-20 at 15:05 +0300, Pekka Paalanen wrote: > On Thu, 16 Apr 2020 17:47:56 +1000 > Christopher James Halse Rogers wrote: > > > On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: > > > Hi, > > > > > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > > > 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 > > Indeed. > > > 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 > removed_in="5"/> and the like) > > How would that work, given the version is negotiated at runtime? > > The message signature structs are now ABI as well, and we have no room > for alternate signatures, do we? > > > > > > > > - event wl_foo.bar introduced in version N sends a wl_fixed in > > > >surface coordinates. version N+1 changes this to a normalized > > > >[-1, +1] 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. > > Something we rarely consider is if you pass Wayland protocol objects > into a library without negotiating the object version with the library > first. For example, we pass wl_surface into the EGL Wayland wrapper > library. If wl_surface would get a version bump breaking backwards > compatibility, meaning that version N+1 changes something that existed > in version N, the library handling only version N would fall apart. > > I sincerely hope this is the only case of a library taking a ready-made > Wayland object in. Getting the version negotiation right needs > inconvenient additions to the library API that I don't think many would > bother or even realize it's needed. > > You can query the version of a wl_proxy, sure, but that does not help > you if it returns a number larger than what your code knows about. > > Btw. this is also a problem in the opposite direction. Let's say you > use a toolkit and the toolkit allows you access to the Wayland protocol > objects. Then the toolkit gains support for new interface versions and > uses them, but your app code is not updated. If the protocol change is > backwards incompatible, your app code may break even if only behaviour > changes and not signatures. Yeah, pretty sure we hit this more than once with XI2. X11 has this property too, the client is not monolithic and different parts of it expect different protocol versions and want their own interaction with the protocol stream. If that includes event delivery you suddenly need to be very careful that the app doesn't deselect the events you need... I believe some protocols address this by putting a "channel" abstraction just beneath the client: one socket connection, N channels, each channel has its own ID space, you can share resources among compatible channels but it's an explicit import operation. In X11 terms you could have the GL driver select for the Present / MIT-SHM completion event in its own channel without stomping on the client's main loop state. Of course, for things like XI2, if you have two channels demanding different visible behaviour, you're still up a creek. But you would at least have the possibility that the client could get it right. - ajax ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: Protocol backwards compatibility requirements?
On Thu, 16 Apr 2020 17:47:56 +1000 Christopher James Halse Rogers wrote: > On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: > > Hi, > > > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > > 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 Indeed. > > 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 removed_in="5"/> and the like) How would that work, given the version is negotiated at runtime? The message signature structs are now ABI as well, and we have no room for alternate signatures, do we? > > > >> - event wl_foo.bar introduced in version N sends a wl_fixed in > >>surface coordinates. version N+1 changes this to a normalized > >>[-1, +1] 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. Something we rarely consider is if you pass Wayland protocol objects into a library without negotiating the object version with the library first. For example, we pass wl_surface into the EGL Wayland wrapper library. If wl_surface would get a version bump breaking backwards compatibility, meaning that version N+1 changes something that existed in version N, the library handling only version N would fall apart. I sincerely hope this is the only case of a library taking a ready-made Wayland object in. Getting the version negotiation right needs inconvenient additions to the library API that I don't think many would bother or even realize it's needed. You can query the version of a wl_proxy, sure, but that does not help you if it returns a number larger than what your code knows about. Btw. this is also a problem in the opposite direction. Let's say you use a toolkit and the toolkit allows you access to the Wayland protocol objects. Then the toolkit gains support for new interface versions and uses them, but your app code is not updated. If the protocol change is backwards incompatible, your app code may break even if only behaviour changes and not signatures. > >> - 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
Re: Protocol backwards compatibility requirements?
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 wrote: > > Hi, > > > > On Monday, April 13, 2020 1:59 AM, Peter Hutterer > > 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 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 > > >[-1, +1] 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.
Re: Protocol backwards compatibility requirements?
On Wed, Apr 15, 2020 at 14:27, Simon Ser wrote: Hi, On Monday, April 13, 2020 1:59 AM, Peter Hutterer 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 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 [-1, +1] 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. ___
Re: Protocol backwards compatibility requirements?
Hi, On Monday, April 13, 2020 1:59 AM, Peter Hutterer 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 > [-1, +1] 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. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Protocol backwards compatibility requirements?
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: - event wl_foo.bar introduced in version N sends a wl_fixed in surface coordinates. version N+1 changes this to a normalized [-1, +1] range. - 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. - 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. 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. 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. So... what's our official stance on protocol backwards compatibility requirements for clients binding to new versions? The last bit is important, this is not a discussion about an changing existing version, merely about future ones and binding to newer versions is opt-in for both compositor and client. Cheers, Peter ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
