Unstable protocol name breakage

[Jonas Ådahl]

On Fri, Oct 30, 2015 at 05:03:29PM -0700, Bryce Harrington wrote:
> On Tue, Oct 20, 2015 at 10:22:45AM +0800, Jonas Ådahl wrote:
> > Hi again,
> > 
> > I was about to start migrating generic protocols away from weston into
> > wayland-protocols. The idea was to start with input-method.xml, text.xml,
> > linux-dmabuf.xml, presentation_timing.xml, scaler.xml and xdg-shell.xml. The
> > question, however, is what to do with the names, because some names already
> > have the form "wl_[name]", and renaming such an interface to "zwl_[name]1"
> > during the unstable period, and then back to "wl_[name]" will cause potential
> > breakage because some implementations in the wild might expect the "wl_[name]"
> > to be the original (ancient) version.
> 
> With Wayland just now starting to be end-user usable, it seems imprudent
> to risk changes that may lead to breakage or developer frustration, even
> when the changes may make things better down the road for future Wayland
> users.
> 
> However, for protocols that we don't really want exposed to end-users,
> or that we don't want to be locked down to maintain as stable
> interfaces, breaking things *now* while adoption is still in flux, is
> probably better than breaking things later.  Plus it might flush out
> functionality that really should be added to more core protocols.
> 
> I agree with what others have already said - deprecate protocols that
> are mostly just clutter now, rename what we intend to continue
> experimenting with, and things we're worried my have legitimate life in
> the wild we should leave them named as is but put a priority on
> getting them officially stabilized.
>  
> > As mentioned before, I have already moved the fullscreen shell protocol, and
> > with the naming schema changes in place, it ended up with the protocol name
> > "fullscreen-shell-unstable-v1", the interfaces zwl_fullscreen_shell1, and
> > zwl_fullscreen_shell_mode_feedback1.
> > 
> > linux-dmabuf.xml is also easy. Since it is already 'z' prefix, to comply with
> > the intended naming schema, I'd just need to rename the interfaces to
> > zlinux_dmabuf1 and zlinux_buffer_params1, and the protocol to
> > linux-dmabuf-unstable-v1.
> > 
> > presentation_timing.xml: I suppose this one can be renamed without any
> > significant implications, since it currently is completely prefix free. I
> > imagine it'd be zwl_presentation1 and zwl_presentation_feedback1 in a
> > presentation-timing-unstable-v1(.xml) protocol.
> > 
> > The problem is the rest of the protocols, since they all already have the
> > intended stable names. This means we cannot apply a naming schema that intends
> > to finally remove the prefix and postfix when declaring stable, since that
> > would collide with the initial name. How to deal with these names needs to be
> > decided, and probably so protocol by protocol.
> > 
> > scalar.xml: As far as I know, Pekka has plans to change scalar.xml, and plan to
> > do so with a name change. So as far as I understand, we need to rename this
> > one.
> >
> > input-method.xml: This one I think might actually be fine to just apply the
> > naming schema, as the protocol itself has Wayland core principle violations
> > that need to be solved, i.e. any implementor of this is already broken (by
> > principle).
> 
> +1 to renaming scalar.xml and input-method.xml

I've been waiting with touching scalar.xml since IIRC Pekka mentioned he
was going to rename it to something else, and when that something is
known, I'd just go with that name.

> 
> > text.xml: This one I'm not so sure about. Has it ever been implemented outside
> > of weston except only as a proof of concept? Would it be fine to use the same
> > name?
> 
> Looks like it hasn't received changes of significance for a few years.
> And it's the sort of thing that if people are using it outside Weston we
> *really* ought to know, so we can maintain it properly.
> 
> +1 to renaming this one with a vengence.  Looks like only editor uses it
> in weston so shouldn't be too hard to do.
> 
> > xdg-shell.xml: Should we bite the bullet and rename this one, or just continue
> > letting its stability state be non-discoverable? It's clearly already used, and
> > renaming it will be painful, so not sure about this one.
> 
> For this renaming effort, maybe skip this one.
> Probably better to handle as a special case, separately.
> 
> > Then comes the IVI protocols. I have no opinions about these, and I don't know
> > what any plan with them might be. Should they be moved, or are they purely a
> > weston thing?
> 
> I thing these belong to kind of a separate category.  I would suggest
> skipping them as well.  If it makes sense to rename for conformance then
> the IVI team should probably make that determination and undertake the
> change on their own discretion.

Yea, it feels a bit out of scope for wayland-protocols. I could be
convinced otherwise by the maintainers of the ivi protocols would prefer
to follow the same procedures.

> 
> > For the rest of the protocols (desktop-shell.xml, screenshooter.xml,
> > text-cursor-position.xml, weston-test.xml, workspaces.xml) I plan to leave them
> > be, as they either are purely weston internal, simple toy protocols or have no
> > consesus that they are to be ever be official protocols. 
> 
> Perhaps protocols that are purely weston-internal should follow suit
> with weston-test.xml and adopt weston- as the prefix, so as to avoid any
> future ambiguity?  Does this just include screenshooter.xml and
> desktop-shell.xml?

Yes, sounds like a good idea.

> 
> Which are toy protocols?  I'd almost prefer to drop these, just to
> eliminate confusion.  If they're demonstrating something too important
> to warrant dropping them, then that'd probably suggest they should be
> experimental or wayland-internal and renamed accordingly.

I was thinking about text-cursor-position.xml and workspaces.xml. They
fill some kind of function, but doesn't seem to be serious attempts at
creating a protocol (workspaces.xml in particular, it was only meant as
an example of how one could implement move-to-workspace-above etc).
Either we them in weston and prefix them, or we remove them and loose
functionality.

> 
> > So what should we do about these naming issues? It should have been clear that
> > all of these are experimental protocols, but due to the fact that some may have
> > started to use these outside of weston anyway even though they being
> > experimental, is it Ok for us to start causing them to break? If not, what may
> > some alternative names be?
> 
> Apart from xdg-shell and ivi, the protocols don't appear to be that
> widely used.  And if they are, it would be better to know about them so
> we can deal with them before they become too widespread for us to ever
> change.

I would hope that copying arbitrary XML files out of weston would be
knowingly risky, and non-functional on non-weston, so I think we can be
selectively unforgiving here. With a more formal distribution model of
unstable protocols, I don't expect us to know that much more about
usage, but at least we can now remove and break things without starting
to crash clients.


Jonas

> 
> Bryce