State of Wayland protocol development

Fri Oct 9 06:36:29 PDT 2015

On Fri, Oct 09, 2015 at 02:11:28PM +0100, Daniel Stone wrote:
> Hi,
> 
> On 9 October 2015 at 11:15, Jonas Ådahl <jadahl at gmail.com> wrote:
> > On Fri, Oct 09, 2015 at 12:36:54PM +0300, Pekka Paalanen wrote:
> >> On Fri, 9 Oct 2015 14:41:31 +0800
> >> Jonas Ådahl <jadahl at gmail.com> wrote:
> >> > I implemented one of the brought up ideas to see how it'd work.
> >> > More specifically, I created a repository called "wayland-protocols"[0]
> >> > and adapted weston[1] to use it for the fullscreen shell. I also added
> >> > pointer gestures to make it obvious that its not only protocols that are
> >> > implemented in weston that are part of it.
> >> >
> >> > The way I imagine it would work is, for new protocols to be introduced,
> >> > it'd have to be a agreed upon "correct" path (i.e. probably not
> >> > wl_absolute_coordinates etc), which should simply mean that such a
> >> > protocol should have been at least Acked-by one or more core developer
> >> > that have acknowledged that it is a suitable thing to do in the Wayland
> >> > ecosystem.
> >> >
> >> > Protocol changes (including introduction) would also require
> >> > Reviewed-by's by someone with enough knowledge*, and if a protocol has a
> >> > maintainer(s), at least Acked-by one of them.
> 
> Excellent. One really important thing I think to have would be some
> documentation around the protocol: what are the known open issues /
> missing pieces / pitfalls? What is the rough plan going forward - is
> it expected to be marked stable imminently, or expected to be
> rewritten? We should really make this a hard requirement, rather than
> having to search through the list every time to remember the most
> recent discussion on it.

I wonder if this could be done via directory structure. Something like:

stable/ - .. well, stable
unstable/ - in-progress, future goal is being declared stable
deprecated/ - deprecated for some other reason, at some point removed

With each protocol having a README with some kind of plan / status and
a list of maintainers.

> 
> >> > Releases of this repository would not be tied to releases of
> >> > wayland/weston, and it wouldn't be a requirement to have a protocol
> >> > implemented in weston to make it part of a wayland-protocols release.
> >> >
> >> > Fast paced protocol development would be done on topic branches, and
> >> > wouldn't be part of any release until properly reviewed. External
> >> > projects would be encouraged to not release software releases that
> >> > exposes such intermediate versions; if expected to use a common
> >> > namespace, they should use a version from a wayland-protocols release.
> >> >
> >> > Declaring a protocol stable could either be done by doing the renaming
> >> > and moving it to wayland, or we could just move it to a stable/
> >> > subdirectory in the same repository. I actually think this might be a
> >> > better idea, so that we don't tie down protocol development to the
> >> > reference compositor release cycle.
> 
> Yeah. Given that we've decided that new protocols shouldn't be a part
> of libwayland-client, I think maintaining it externally to the core
> library is pretty attractive.
> 
> >> > Patch merging could be done in the same way as with wayland/weston,
> >> > assuming the patch merger makes sure the right persons have acked or
> >> > reviewed.
> >> >
> >> > Release management could either be done by the wayland/weston release
> >> > manager or someone else. I could volunteer doing this if no one else has
> >> > a strong urge.
> >> >
> >> > For the more practical parts, the protocols in the repo now have
> >> > versions in the XML file names and in the protocol element attribute, but
> >> > not in the interface names. Having version numbers in the interface names
> >> > would enable us to implement multiple versions in clients and servers,
> >> > but it'd mean that each interface would have both a _ prefix and a
> >> > version number. Maybe thats fine, and I wouldn't object if someone thought
> >> > that would be better. It'd get rid of the redefinition of interface
> >> > versioning for unstable protocols.
> >> >
> >> > I still have the '_' prefix which, mentioned by Pekka, violates some
> >> > rule in C. I'm not sure we need to care (we've been doing this in weston
> >> > since 2013), but if anyone has a better suggestion or objection please
> >> > say so.
> 
> Unfortunately it does, and I think it makes newer g++ in particular
> quite unhappy. dmabuf is currently using 'z' as an experimental
> prefix, which seems reasonable enough - but again that falls into the
> stable-naming problem. If zlinux_dmabuf v7 is the blessed stable
> version, then it means clients written to zlinux_dmabuf v7 have to
> completely unnecessarily port everything to being linux_dmabuf v1. I'd
> be much more in favour of keeping a single stable name throughout its
> development.

My idea of this is that, an experimental/unstable protocol is just that.
When declared stable, it's more or lesst the final break. If you want to
have linux_dmabuf with no special unstable naming during all of its
development stages, then that means you start being stable at version 1,
with the difference that it may be incomplete. The point of unstable
protocols is that changes may break the protocol, and to make tha
possible, we need to do a rename when declaring it stable. It's the pain
that comes with being an early adopter, while still enabling the
possibility to actually fix the protocol during its early stages instead
of duct tape it.

If you see some way to avoid renaming then please explain, because its
not clear to me how (across multiple projects and code bases) it'd work.

z prefix sounds reasonable to me anyhow; meannig zwl_fullscreen, etc.

> 
> >> > FWIW, the way things are structured in the repo now, it is possible (and
> >> > enabled) to install unstable XML files. Copying would work as well. All
> >> > these these minor practical details I don't have a strong opinion on,
> >> > and I'd be happy change them if needed.
> >> >
> >> > If we want to take this path with a protocol repository, after agreeing
> >> > upon the details, I'd continue with moving away the generic protocols
> >> > from weston, applying some "unstable protocol" rule regarding xml,
> >> > protocol and interface names, and change weston to start using files
> >> > from wayland-protocol (copied or installed).
> >> >
> >> > Thoughts?
> >>
> >> I have no objections. Seems like it'd work. You have a different XML
> >> file name for each incompatible version, so there won't the problems in
> >> projects directly depending on this repo being checked out or installed.
> >>
> >> If this really solves some problems we have, I'm all for it.
> >>
> >> One thing we could add is a list of protocol maintainers if assigned,
> >> so it would be clear who to get an ack from. I'd take wl_scaler,
> >> presentation and dmabuf for starters.
> >
> > True. We could maintain that in tree, similar to how chromium/Blink does
> > it.
> 
> I'll happily volunteer as a backup maintainer for all three.
> 
> >> I think this would nicely separate the protocol review from
> >> implementation review, in case that has been a problem: if the protocol
> >> has been merged in wayland-protocols master even if unstable, the
> >> implementation in, say, Weston, only needs to be technically reviewed
> >> and reviewers don't have to question the quality of the protocol spec
> >> at the same time.
> >>
> >> > * How to determine this I guess is one of the things that needs to be
> >> >   agreed upon, but I imagine it'd be different set of individuals
> >> >   depending on the area the protocol touches.
> >> >
> >> > [0] https://github.com/jadahl/wayland-protocols (only on github for
> >> >     demonstration)
> >> > [1] https://github.com/jadahl/weston/commit/caf37bb527740b5792260deaabc1ce33678351e5
> >>
> >> The idea of the Weston patch looks good to me too.
> >>
> >> However, could we use git submodule to automate the fetching or a
> >> recent-enough revision of wayland-protocols? It might prevent some
> >> weston FTBFS questions, when we depend on unreleased versions. Or was
> >> the idea to release wayland-protocols often enough so we could always
> >> just rely on the pkg-config version check in configure.ac? That would
> >> be fine too.
> >
> > I don't think we should restrict ourself to using it as a git submodule.
> > It would for example not be possible if you use Mercurial or some other
> > version control system (SDL comes to mind as an example of that).
> > Releases could be made on-demand, meaning it wouldn't be a problem for
> > weston to depend on a particular version.
> >
> > I'd also expect weston master to depend on wayland master as well as
> > wayland-protocols master, far that matter.
> 
> Agreed, but indeed that doesn't preclude Weston from using it as a git
> submodule - just as long as we're considerate of other users who will
> need releases.

True. Not that I see the actual point though (I only see the installing
being less tested).

> 
> Thanks a lot for doing this Jonas; it sounds good to me. How about we:
>   - wait until Monday or Tuesday to see if anyone can pick concrete
> holes in this proposal

AFAIU Wayland development is the least active on weekends so can just
wait for some more days so work-days contributors have the time to
react.

>   - if none, I can create the repository then, with the usual Wayland ACL
>   - patch Weston master to include protocols as a submodule
>   - patch Weston to move its development protocols (xdg-shell,
> linux-dmabuf, presentation_timing, scaler) to protocols
>   - go ahead and commit the protocols you and Carlos have been working
> on (gestures, pointer-lock/rel-pointer, new DnD)
>   - document all of the above

Sounds like a plan to me, except the DND changes poke at wayland.xml and
moving wayland.xml into wayland-protocols/ is not something I've thought
very much about. Should we?

> 
> I'll ack the Weston patches as long as they pass distcheck, and you
> can then just commit them directly.
> 
> Cheers,
> Daniel

Jonas