Proposal for better collaboration on xdg-shell

[Bryce Harrington]

A while back Pekka asked if I'd help look at xdg-shell and how we can
ensure it really does become a cross-desktop standard.  I promised to
engage with the EFL folks and get their feedback, which I posted
recently.

I also promised to look at the Plasma team's comments on xdg-shell.xml
from some months back, and to suggest changes to xdg-shell.xml that
might make it more inclusive to their needs too.  However, in looking at
the prior discussions around KDE's feedback, and especially seeing the
tenor of discussions regarding this recent EFL feedback, I'm seeing some
really bad anti-patterns at work:

 1. There is really no substitute for getting the DIRECT feedback from
    the compositor implementers.

 2. It is proving impossible to get all the D-E stakeholders to
    deliberate in real-time.  Everyone's implementing Wayland on widely
    dispersed schedules.

 3. Developers seem to not want to pin down their needs specifically
    until they're in the midst of their own Wayland development.  But
    then they need their protocol fully fleshed out ASAP so they can get
    the work completed.  Development can't wait on committees.

 4. Once a D-E has finished compositor implementation, there is little
    incentive to entertain changes, esp. if they got their work into the
    standard already.  The first implementor thus gains a
    game-breakingly strong first-mover advantage in our protocol
    development process.

 5. The early adopters will then be on defensive to *prevent* further
    changes.  Their motivation will thus be to lock down the protocol as
    unchangeable (probably earlier than it should) and suggest everyone
    else make their changes in their own private protocols.

 6. If you're not the first D-E contributor, getting your changes in
    will be an adversarial process.  As this can be frustrating, you are
    motivated to take the alternative and just do your own thing as
    a private protocol, and just modify the subset of clients you care
    about to support that protocol.  You decide to let cross-desktop be
    Someone Else's problem (goto 1).

 7. Ultimately our collective goal and reason we're bothering with all
    of this to begin with, is to establish a lowest-common-denominator
    protocol(s), that an arbitrary third-party client can rely on when
    ensuring their software will be portable across a plethora of
    desktop environments.

    a.  Otherwise:  Fragmentation

    b.  Also, declaring a desktop standard which no one in Linux
        actually follows makes us look dysfunctional.  We deserve all
        the laughs that we get.


Given that steps 1-6 seem unlikely at producing #7, I don't think that
just more poking at the API is going to get us across the threshold.
What we need is a better process for developing the protocols in the
first place, which respects late-comer feedback and rewards
collaboration rather than just being first.

I.    Desktop environments are expected to maintain their own private
      protocol(s) in their own repositories.  These can correspond to
      what they actually use, and what they expect clients to use.

II.   Weston's current protocol/desktop-shell.xml is renamed to
      protocol/weston-desktop.xml[1] as it is considered a Weston
      private protocol.

III.  A new repository is established on freedesktop.org.

      0. This repository exists under the purview of the Wayland
         project:

          http://cgit.freedesktop.org/wayland/desktop-protocols/

      1. Alternatively, we establish a subdir within the xdg-specs
         repository under the purview of the Freedesktop Specifications
         project, such as:

          http://cgit.freedesktop.org/xdg/xdg-specs/wayland-desktop/

IV.   A 'proposed' subdirectory is added to the
      wayland/desktop-protocols git repository.  Per-desktop environment
      subdirectories are created in this repository named
      proposed/<desktop-environment>/, containing proposed protocol
      standards they wish to suggest other desktop environments follow.
      For example, these could be protocols the D-E considers stable for
      itself.

      0. These protocol files should scope their globals and interfaces
         with identifiers unique to that D-E.  It's also recommended
         that the generated C symbol names also be scoped to avoid
         clashes with the other D-E's.

      1. Lesser-known D-E's are welcome.  In particular, any D-E
         mentioned on Wikipedia's D-E page will be gladly received.
         https://en.wikipedia.org/wiki/Desktop_environment

      2. D-E's should first obtain push access from FDO to the
         repository for their principal compositor developers, then add
         a subdirectory for their D-E.  These individuals are welcome to
         push directly to their subdirectory; no gatekeeper review
         required.  Do not push to other D-E subdirs or to the common
         standard spec directory without their review and Okay.

		 A README is required in the D-E's proposal subdir.  This will
		 describe what the protocols are, and identify their development
		 status including if they are considered stable (see #6 below).

      3. Weston gets its own subdirectory proposed/weston/.  The current
         xdg-shell.xml has been reviewed and accepted by the Wayland
         community so moves here, and is renamed to
         proposed/weston/desktop-shell.xml[1].

		 The weston source package will require this desktop-protocols
		 package to be installed as a build requirement.  Thus, the
		 xdg-shell.xml needs to be kept in sync with with what weston
		 actually implements.  IOW, if someone proposes changes to this
		 file, they need to also land an implementation of the changes
		 in the reference compositor.

      4. Whereas the current xdg-shell.xml was developed with GNOME's
         requirements particularly in mind, a copy of xdg-shell.xml is
         added to proposed/gnome/desktop-shell.xml[1] GNOME-specific),
         to be further developed at GNOME's perogative.

      5. Perhaps with the exception of #3, no one is obligated to follow
         these proposals.  In particular, clients musn't assume these
         protocol APIs are implemented by the proposer; clients should
         instead use the D-E's own published protocols (see I).

      6. No guarantees of stability are implied for any of the protocol
         files under proposed/.  D-E's are welcome to scrap and rewrite
         their proposals at their discretion.  That said, the
         fundamental premise of this system is to enable D-E's to borrow
         protocols from one another and evolve towards commonality, and
         in so doing to grow in interoperability.  Thus, giving some
         consideration to stability/versioning/backwards-compatibility
         may facilitate the larger goals; this should be mentioned in
         the README (see #2 above).


III.  A new (blank) fdo-shell.xml[2] is created at the top level in the
      wayland/desktop-protocols repository to serve as an official
      cross-desktop protocol.

      0. Protocol elements (interfaces, globals, etc.) in this file
         must be prefixed with 'fdo'.

      1. Protocol elements can be moved here from the
         proposed/<desktop-environment>/desktop-shell.xml[1] files when
         at least 4 desktop environments are proposing the exact same
         thing.  While it's not a D-E itself, it is recommended (but not
         required) that weston be one of these four, as it is the
         reference compositor.  D-E's claiming Wayland support are
         encouraged to implement this protocol.

         Protocol elements promoted in this way are considered
         'unstable' and may be subject to change at the discretion of
         the Wayland developers.

      2. At the Wayland developers' discretion, portions of this
         fdo-shell.xml[2] in weston can be declared 'stable'.  

         Wayland, such as for protocol elements that all (or nearly all)
         desktop environments support.  D-E's claiming Wayland desktop
         protocol support must implement this protocol.

      3. The Wayland developers may also declare portions of the
         fdo-shell.xml[2] as 'deprecated', in which case the compositor
         should log or display a warning when those API's are used.

         Portions may also be declared as 'obsolete'; compositors should
         not advertise these at all.


Notes
-----
1:  I picked 'desktop-shell.xml' as (to me) the most obvious name for
these files, but understand this is likely to be a heavily bikesheddable
item, so for sake of this document just consider it a place-holder.
It'd be nice if we were all naming this consistently, but I don't think
it matters if every D-E calls it something unique, so long as it's clear
that it contains the proposed protocol items for fdo-shell.xml[2].

2: 'fdo-shell.xml' is my own bikeshed of xdg-shell.xml.  Historically,
XDG is an acronym for the 'X Desktop Group' that later renamed itself to
freedesktop.org.  The acronym was retained by the group for prefixing
purposes (essentially deprecating the definition), with its use
especially expanded with due to the Portland Project (xdg-utils, et al).
I've heard it backronymed to 'Cross-desktop Group'.  Still, the X
reminds people of X11 and so I think may be confusing or at least
non-obvious.  FDO seems to be to be both more accurate and less subject
to confusion.

Bryce

1: https://en.wikipedia.org/wiki/Freedesktop.org