State of Wayland protocol development

Pekka Paalanen ppaalanen at
Mon Sep 21 05:28:28 PDT 2015

On Fri, 18 Sep 2015 22:44:16 +0800
Jonas Ådahl <jadahl at> wrote:

> On Fri, Sep 18, 2015 at 04:35:52PM +0300, Pekka Paalanen wrote:
> > On Fri, 18 Sep 2015 15:00:19 +0800
> > Jonas Ådahl <jadahl at> wrote:
> > 
> > > Hi,
> > > 
> > > I'd like to start a discussion on the state of how development of Wayland
> > > interfaces are done and how they should be done, though less about the
> > > technical aspect of it.

> > All this requires clearly denoting which parts are more stable and
> > which are considered experimental within Weston, both protocol files
> > and implementations. Directory structure? Protocol interface names?
> Are there any protocols in weston that are "stable"? Which ones would
> that be? If it really were stable, wouldn't they be moved to wayland to
> make it official? Sure we can have different levels of "unstable",
> moving xml files between directories or something, but not sure what we
> win doing that.

Weston's internal protocol interfaces (e.g. screenshooter.xml) are
essentially stable - more precisely, they should follow Weston's plugin
ABI stability rules. This is something we have never talked about
before, but I think it makes sense. Maynard is an external project
using desktop-shell.xml and needs a plugin to work.

Not only protocols, but Weston's code also is important to classify.
Weston's core is used in many places and we'd like to keep the core
stable (as in not too buggy). Things like desktop-shell/*.c or
ivi-shell/*.c are more on the unstable side.

All these have even now slightly different review requirements we
haven't really talked about, so I think people do it by feeling, erring
on the safe side.

> > Should we be using a different Weston branch for including all the
> > experimental stuff while leaving master for "stable development"? Nah,
> > I think that might become a mess.[*]
> I don't think we should. Branches will bit-rot and it will be a pain to
> have to rebase them over and over again. They will also be harder to
> discover and test. The main goal really is to make it more obvious where
> to find in-progress protocols, and I don't think hiding them in branches
> helps that much.

The idea was to periodically merge master into the topic-branch, not
rebase. So a topic-branch would be easily at least as recent as master.

I first thought one branch for everything experimental and rejected
that idea, but topic-branches is an idea I haven't rejected yet.

When someone wants to propose a topic branch to be merged, it is easy
to generate the diff to master. Reviewing that would be hopefully
easier than rebase/squash/resend cycle, and it wouldn't invalidate old

> > What do you do when you do a backward-incompatible change to a protocol?
> > 
> > - Rename the globals or the protocol file? This would make people think
> >   twice about the change as it would incur lots of churn in the code.
> >   The churn shouldn't be a problem for review, since we wouldn't review
> >   experimental implementations carefully. But it's still churn.
> The way I've done it and also the way we did with pointer gestures is to
> prefix all of the interfaces with an underscore, with a note in the
> global interface's description describing the limitations and lack of
> backward compatibility as well as future intentions. See here[0] for
> exact wording.

Doesn't leading underscore touch the "reserved names" of the C spec or

> I think we should consider doing this to on all our experimental
> protocols in weston (either that, or move them to wayland). And we
> should probably move out the private protocols to a separate directory
> as well.


> > - Use the mechanism tried with xdg-shell? A request to make-or-fail a
> >   specific experimental version. This seemed like a good idea, we just
> >   have to document it clearly and make sure it's followed properly.
> >   E.g. the make-or-fail request *must* always be opcode 0. We could
> >   have helpers for that.
> No. That mechanism doesn't work, because it is not possible to discover
> what version is implemented. A client that supports both xdg_shell and
> wl_shell have no way of detecting (except try - be killed - try again)
> whether it can use xdg_shell or wl_shell. The above described approach
> does not have this limitation.

When I read your earlier comment, I thought make-or-fail was exactly
what you were describing. I stand corrected.

Instead you want to change the interface version semantics of the
advertisement. I'm not sure I like that or not. But it's just details...

The danger with it is that people might confuse the experimental
versioning scheme with the normal versioning scheme, and assume that
also stable protocols must always be bound at the exact advertised
version. This would hopefully be solved with documentation.

> > Btw. I have been thinking that when one stabilizes a protocol extension
> > and moves the .xml file into the Wayland repository, we should also
> > always rename the global interfaces and the .xml file. This would be
> > the last protocol break, that allows us to remove any make-or-fail
> > requests while also ensuring no-one will accidentally use it with old
> > code, and it won't clash with any copies of the experimental xml file.
> I agree. This is something I've taken into account when writing and
> reviewing new protocols (as described above). But, what would be the
> point of renaming the XML file?

So that build scripts could not accidentally use an XML file from
a wrong directory and it would make it obvious which XML file is
experimental. That's all, I think.

> The other part I brought up was adding to stable protocols. Currently
> being discussed are additions to wl_data_device_manager (DND actions),
> wl_seat (release request), wl_pointer (axis sources), wl_touch
> (touch "focus" changes). Who are in charge of allowing such changes?
> Some are quite huge (DND actions) and without a consensus, while the
> other are relatively small, and thus with a consensus easier to reach,
> but who's responsibility is it to make the call?

Whoever is a known expert on that area.

Who decides who is an expert? Uhh...

Technically, people with push rights make the final decision to push or
not. I'd love it if it was easy to decide what to push and what not,
but it isn't and I don't think it can be as everyone evaluates everyone
else differently and based on the topic at hand.

Would you like to push more to Wayland and Weston?
What do you need to be able to do that?

My view is Weston-centric as I don't work on any other compositor. My
biased preference for not-desktop-specific extensions that aim for
Wayland core is to be developed in Weston, be that in topic-branches or
otherwise. Topic-branches would get the stuff off the mailing list
early, and merging a topic-branch to master would correspond to what we
currently have with landing patches to master.

I have a feeling, that we're trying to engineer a solution to a
political and time management problem. I'm not sure that having
alternative patch landing places with reduced requirements is going to
solve things. Why wouldn't things rot there the same way they do on the
mailing list? You still have to do the same decisions in the end anyway.

Sorry I don't have any better answers.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <>

More information about the wayland-devel mailing list