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

[Jonas Ådahl]

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.

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.

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.

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?

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

> 
> > Another protocol left to migrate is scalar.xml. I didn't do this yet
> > because Pekka had plans on renaming it, and I'll simply wait until he
> > has a name for it before migrating anything.
> 
> Yeah, inventing a new name for it is hard, but I'll try to come up with
> something. Something that implies both scaling and clipping...
> something used to create viewport objects...
> 
> > Other than that, the wayland-protocols have shaped up some, with the
> > pointer gestures protocol as well as the protocols of this series
> > migrated there. I wouldn't mind if people went and had a look to see if
> > there are any opinions of how things should work before we make an
> > initial release. The procedures and some details are explained in the
> > README file in the toplevel directory.
> 
> The README looks fine to me on the whole, I sent you some trivial typo
> fixes for your consideration.
> 
> This puzzles me a bit:
> 
> 	"Each release of wayland-protocols finalizes the version of the
> 	protocols to their state they had at that time. Between each
> 	release, backward incompatible changes can be made to both
> 	stable and major unstable protocol versions as long as the
> 	requirements are held upon release."
> 
> It says backward-incompatible changes could be made to also stable
> protocols as long as stability is maintained from release to release.
> Essentially it means that such changes have to be reverted before the
> next release. Is that just to account for accidents?
> 
> If wayland-protocols is intended to be released often and as-needed, we
> should make sure we don't need such reverts to begin with. Otherwise
> the release engineer will have a big review burden. IOW, we should keep
> the repo in an always releasable state.
> 
> In short, I wouldn't mention the stable protocols in this paragraph.

Yea, not happy with that paragraph. Actually I think the first sentance
is enough, i.e. we can drop evereything after "... had at that time. The
intended purpose was to make it clear that it's allowed to do 'oops,
thats not what i meant' fixups, but that should be clear already I
suppose.

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

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

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.

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

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

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.


Jonas

> 
> 
> Thanks,
> pq