Unstable protocol name breakage

[Bryce Harrington]

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

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

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

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.

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

Bryce