[PATCH weston 00/10] weston wayland-protocols migration

[Pekka Paalanen]

On Fri, 6 Nov 2015 10:39:12 +0800
Jonas Ådahl <jadahl at gmail.com> wrote:

> On Thu, Nov 05, 2015 at 12:21:21PM +0200, Pekka Paalanen wrote:
> > On Wed,  4 Nov 2015 16:49:49 +0800
> > Jonas Ådahl <jadahl at gmail.com> wrote:
> > 
> > > Hi,
> > > 
> > > This series changes weston to depend on wayland-protocols for the
> > > majority of the protocols previously in the protocols/ directory. The
> > > protocols moved are also renamed to comply with the unstable naming
> > > conventions of wayland-protocols, with the exception of xdg_shell which
> > > will use the current name until the next version.
> > > 
> > > I'd appreciate if maintainers of given protocols could at least Ack the
> > > patch changing their protocol implementation, as a semi formal stamp of
> > > approval of the name change.
> > 
> > Hi Jonas,
> > 
> > I'll give any detailed feedback as replies to the patches, here are some
> > overall comments.
> > 
> > > Other than that, the workspaces protocol is removed, mostly because it
> > > wasn't a significant enough proof of concept needed for any particular
> > > feature. text-cursor-position.xml however I have left intact, because
> > > without it the zoom accessibility feature proof of concept becomes
> > > a bit too useless. I'd prefer to prefix it with something like toy_ or
> > > weston_, but would like to hear input on this one. Given that it is
> > > completely undocumented it is quite far from a real attempt, but it
> > > seems like something that will be needed sooner or later for
> > > accessibility reasons, so not sure what to do with it right now.
> > > 
> > > Things that seemed more weston specific was weston_ prefixed. The
> > > screenshooter protocol and the desktop shell protocol fell into this
> > > category.
> > 
> > Speaking of prefixes, do we have an idea what protocols should use the
> > wl_ prefix and what shouldn't?
> > 
> > I have had the feeling that wl_ is only Wayland core. But what does
> > Wayland core mean? And wl_shell is an exception already.
> > 
> > Should we restrict wl_ to only for things in wayland.xml? Probably not,
> > as I think wl_ in e.g. wl_scaler is justified since it's a "low-level"
> > generic feature, and yet wl_scaler will not be added into wayland.xml.
> > 
> > Perhaps wl_ prefix should be reserved for extensions that are usable
> > regardless of a shell or environment. I'm not sure if the input method
> > extensions would be eligible for wl_ or not, or what to do with
> > fullscreen shell.
> > 
> > xdg_shell is setting a precedent for using xdg_ prefix for all
> > desktoppy but still DE-agnostic extensions, and I think that is fine.
> 
> We discussed this last night on IRC and you expressed that you thought
> that the wl_ prefix should be limited to only libwayland-client and
> libwayland-server and nothing else.

Indeed.

The rationale I gave in IRC is that if we look at how the wl_ prefix is
currently used, unstable protocols notwithstanding, we have it for
normal libwayland functions and protocol interfaces in wayland.xml. The
common factor here is that they all are in libwayland (which even
installs generated C bindings for wayland.xml), so it would be logical
to have wl_ mean "Wayland library".

The earlier interpretation of wl_ meaning "Wayland core protocol" was
encumbered by libwayland having non-protocol functions and types with
that prefix and wayland.xml containing wl_shell. We don't really think
wl_shell as Wayland core because it is specific to desktops, I think.

> The resulting idea after that discussion was to use the wp_ prefix
> instead of wl_ prefix for future protocols with the exception of the
> rare cases where new interfaces actually have to be added to
> wayland.xml. I don't know of any examples or plans where this is needed
> yet.
> 
> This means wl_scaler would become wp_scaler, wl_fullscreen would become
> wp_fullscreen, wl_presentation wp_presentation, etc.

wp_ is just whatever came first to my mind, from "Wayland protocol".

I'd like to say "better suggestions welcome", but I don't want to delay
this work on bikeshedding on it, so I'll just say: "if there is a good
reason to not use wp_, tell us now!"

> We also somewhat concluded that generic sounding name (linux_) should
> also be prefixed, meaning linux_dmabuf will become wp_linux_dmabuf, but
> maybe we should really use some other prefix for non-generic protocols?
> I'm not sure.

wp_linux_dmabuf works for me, and should address the concerns Daniel
Stone had about namespace clashes. I think wp_linux_ is appropriate: it
is generic in the sense that it does not have any ties to shells, DEs or
other non-generic extensions, and it is specific to linux (until other
OSs implement dmabuf support).

Whether non-generic extensions use prefix foo_ or wp_foo_, I don't
really care per se. If foo_ alone is distinguishing enough, I'm ok
either way. However, using wp_ prefix for a non-generic extension
without any other prefix is something I'd like to avoid. IOW, I would
not like e.g. wp_popup, because popups are inherently a shell concept
and therefore need scoping to the shell protocol.

> Regarding the xdg_ prefix, nothing in particular was concluded. I'm not
> sure wp_xdg_ is desirable, but maybe its not that bad. We'll have to
> bite this bullet the next time xdg_shell changes, or if some other
> protocol depending on xdg_shell is introduced. Opinions? Stay with xdg_?
> wp_xdg_? wpxdg? wxdg? wp_desktop_shell? Something else?

If those are awkward, how about de_?

> Anyhow, I will add the concluded parts to the README.

> > 
> > I looked at the Presentation (feedback) extension in wayland-protocols,
> > and I saw that you renamed both global and non-global interfaces.
> > 
> > Do we need to rename also non-global interfaces according to the
> > unstable naming convention?
> > 
> > I assumed renaming the globals would be enough, because it is enough to
> > bring the runtime discoverability. Renaming also non-global interfaces
> > seems needless churn on one hand, but it does make it painfully clear
> > to a developer upgrading to a new major version which places he needs
> > to review in the code for changes.
> 
> The reason is to make it at least possible to implement two versions of
> the same unstable protocol in one file. If we'd include
> "foo-unstable-v2-server-protocol.h" and
> "foo-unstable-v3-server-protocol.h" the non-global interfaces would
> collide.

That is a good practical justification. Ok!

> > > One current inconvenience that would be nice with some opinions is what
> > > to do with unstable protocol files after a protocol has been declared
> > > stable. Currently specified to work by having one directory containing
> > > the stable XML file together with a README in the stable/ toplevel
> > > directory, and yet another directory containing the unstable protocol
> > > files together with a README in the unstable/ directory. This seems a bit
> > > backward to me. Deprecating a protocol by moving it into deprecated/
> > > would still require us to have the protocol in the stable/ and probably
> > > even in the unstable/ directory. This all is a bit awkward to me. One
> > > idea is restructure the tree a bit and put protocols in the directory of
> > > the current state (stable/unstable/obsolete) and then keep the old XML
> > > files in subdirectories in there, having the Makefile deal with
> > > installing XML files appropriately in the corresponding
> > > stable/unstable/obsolete directories. Or we could have all protocols in
> > > the toplevel directory and always have the corresponding XML files in
> > > stable/unstable/obsolete subdirectories and just installing that. Any
> > > opinions about this?
> > 
> > Do all your ideas still have the same organization when installed as
> > currently produced from wayland-protocols?
> 
> No. The one with all protocols in the toplevel/ would be installed as
> such. I.e. foo/unstable/foo-unstable-v2.xml and foo/stable/foo.xml. But
> this approach is probably my least favorite.
> 
> > 
> > My first thought would be that repository file tree matching the
> > installed file tree would be nice and obvious.
> > 
> > This is how I would imagine the installed tree worked:
> > 
> > - When an unstable extension gets the major version bumped, we get a
> >   new xml file and none will be removed.
> > 
> > - When an unstable extension gets stabilized, a new xml file for the
> >   stable version is added. The unstable versions are still kept around
> >   for some time before removed, so that projects have time to migrate.
> 
> This is the problem. How long is that? We might end up with a stable
> protocol in the unstable/ directory for a long time.

N releases? N months? Does it matter too much? But see below.

> One of the ideas was to move the -unstable-vN- XML files to an unstable/
> or legacy/unstable/ directory in the new directory and add Makefile
> magic to install it in the right place.

But if the installed tree will remain the same, what good does
rearranging the git repository layout do?

> > - When a stable or unstable extension gets obsoleted, all its xml files
> >   get moved into the obsolete/ directory at once. (The README in
> >   wayland-protocols talks about "obsolete", not "deprecated", btw.)
> >   This is a clear signal that an extension is going away by breaking
> >   builds, but with a simple fix-up if a project is not willing to drop
> >   it right away.
> 
> Deprecated is probably a better name than obsolete. Though, I think here
> we should be even more careful regarding breaking builds. We should
> probably, at least by default, install deprecated protocols in the same
> way as before, for some time.
> 
> > 
> > Have I understood that right?
> 
> More or less. The question is whether it would be Ok to break builds,
> and if so how "soon"?
> 
> > 
> > Now the question is, how to map that to the repository directory
> > structure? The current way seems fine to me. Why does it seem backwards
> > to you?
> 
> Mostly because we'd have the same protocols looking like it's in up to
> three concurrent states at the same time. This could be fixed by when
> declaring stable / deprecating actually moving all the files while
> adding Makefile code to make the installed files structure unchanged.

The same question: if installed tree remains the same, what's the
benefit?

Ok, it seems like we need two levels of communication here:
1. announcement that a protocol is stabilized or deprecated
2. breaking everyone's build who uses outdated versions.

Step 1 is usually communicated on a mailing list, but if we need a
clear note in the git repository, and adding a sentence in README is
not visible enough, then, say, let's add a file STABILIZED or DEPRECATED
in the protocol's directory. I think that would have practically the
same effect as moving files around in the git repo and still installing
the same file tree layout, but without the hassle to adjust Makefiles
and checking things actually get installed the right way.

Step 2 is where we change where xml files get installed, which will
break builds that try to use outdated files. This is the forced wake-up
call for all projects, but still not a big deal, because the projects
can just check against the wayland-protocols version on which directory
to find the old files. If they choose to keep on using the old files,
at least they do it knowingly.

I suppose when a protocol is stabilized, then in step 2 we would move
the unstable versions into the deprecated directory rather than remove
them.

Cleaning up, that is, really removing protocols that are not supposed
to be used anymore, can be done after years then.

Would this be satisfactory?

> > I see that having a sub-directory per extension in stable/ is
> > superfluous, as there will be just one xml file per extension. The
> > readmes could be just named by the extension, collected into a single
> > README, or even just appended into the xml files themselves. The
> > unstable/ directory obviously needs sub-directories, and obsolete/
> > probably too.
> 
> I think having protocols as directories in stable/ even when they are
> stable is still preferable. Maybe there will be related data, such as
> SVG diagrams and other things, and that would be impossible/inconvenient
> if everything is thrown in the same directory.

A good point.

> Personally I'm leaning towards declaring stable means moving the XML
> files into a subdirectory in the new protocol directory under the
> stable/ toplevel directory, and having the Makefile install the files in
> the same way as before. Deprecating would work the same. But if there
> are objections to doing things like that I suppose having copies in the
> different stability states are fine.

I'm losing track of all these directories. :-)

I'd suggest the only time we can have a functionally identical copy of
a protocol in more than one place is when the last unstable version is
copied to stable, before the unstable versions get moved to deprecated.

So, what I have in mind in summary:

- unstable protocols we have already figured out
- stabilizing a protocol involves copying it from unstable to stable
  directory, and marking the unstable as deprecated (step 1)
- deprecating a stable or unstable protocol starts with step 1
- when we want to do the wake-up call on a deprecated protocol,
  do step 2
- final removal of deprecated files after step 2 can be done years after

How's that?

I am assuming that the directory structure in the git repository will
match the directory structure of the installed files. I think this
would be more clear than the Makefile installing some with matching
structure and some not. This would also allow using wayland-protocols
without installing it.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151106/a070ba97/attachment-0001.sig>