You are a Linux user using Wayland. You experience an issue with an application that was not there when running the app under X11. Being an issue with your Wayland environment, you file a bug on the Wayland issue tracker.

The bug is closed by a bot explaining that it is not a Wayland issue¹, even though the issue is obviously Wayland-specific. What is going on?

If you just want to know where to file issues, scroll to here.

What is Wayland?

TL;DR: An ecosystem, such as “web”, “macOS”, or “wayland” has many parts.

When you run and interact with graphical applications, it interacts with the platform in primarily two ways:

1. You have generated some input by pressing your keyboard or moving your mouse which your platform’s display server sends to the focused app.

2. An app has rendered some new content² it would like to show and sends the finished “painting” to the display server.

The display server can be thought of as being responsible for collecting user input and managing the display, while the client’s Window System Integration (WSI) is responsible for talking to the current platform’s display server. The app will in its WSI have entirely separate implementations for platforms like for Windows, for macOS, for X11, and for Wayland.

But while there is code for Wayland here, none of this code is part of the Wayland project.

The Wayland project

TL;DR: Wayland is to desktop what HTTP is to web.

The actual Wayland project covers 3 things:

1. Which “messages” the WSI and display server has available: wayland-protocols.

   These are effectively a set of “standards” written in XML. For example, “color management”, with requests, events and required behavior for how to deal with colors.

   You can explore protocols here or here. Many DEs also have their own special-purpose or experimental protocols that have not gone through the Wayland project.

2. How the WSI and display server can send messages on the wire: wayland. This covers message encoding, socket details, and some low-level message primitives.

   This concerns itself with how to send requests, but nothing regarding what those requests should be or should do. You can explore the wire protocol here.

3. A convenience library in C for handling the above socket details and protocol encoding for you: libwayland (part of wayland).

   You can explore the client side of libwayland here, server side here.

The astute reader will notice that none of this actually does anything³. wayland-protocols has a request for sending graphical content, wayland has a way of sending requests, but nothing here makes, sends, receives or uses graphical content.

All that is up to client and server implementations.

Where is the code then?

TL;DR: The app and DE/WM authors write it.

For the app side, the code is the Wayland Window System Integration written by either the authors of the app or the toolkit/library they receive it from. For many apps, the platform specifics are handled by Gtk/Gdk, Qt or Chromium’s Ozone. Exactly the same place you would find the code specific to macOS, Windows and X11.

For the display server side⁴, it is written by the display server authors, in some cases with assistance from libaries like wlroots or libweston. The GNOME team wrote mutter, the KDE team wrote kwin, the Sway team wrote sway (and wlroots to help others), etc.

Difference to X11

TL;DR: More implementations.

While this is technically no different from how X11 is structured (client, servers, protocols, extensions), it is different from how X11 worked in practice.

In X11’s later years, pretty much everyone ran X11’s Xorg as their display server⁵, and instead had DE, WM and compositor as external processes. Under Wayland, each DE/WM is just its own display server. It does mean a bit more duplication on the “hardware handling” front, but is overall a simplification.

Where do I file my issue?

TL;DR: With the app or server.

1. Does the issue have a specific app as common denominator? File the issue with the app - even if the app works fine on other platforms like X11.

   Example: “Autofill does not work in Chromium when using Wayland”, file the issue with Chromium and follow their instructions.

2. Does the issue have a specific DE/WM/display server as common denominator? File it with the specific DE/WM/display server.

   Example: “Context menu appears in right place in GNOME, but wrong place in Sway”, file the issue with sway and follow their instructions.

In either case it might be triaged to a different component, but this would be where to start.

Are there are no issues in Wayland?

Of course there are, but:

1. The vast majority of code and logic is within, and specific to, the apps and display servers in question.

   Studies have found with overwhelming evidence that bugs are attracted to code, even when other food sources are available.

2. When there are issues with Wayland protocols or their design, the developers working on those apps or servers reach out in Wayland forums to discuss.

The user experience of an end-user is built by the app and server teams, and those teams - Chromium, Gtk, Qt, etc. - participate in the Wayland development with their experiences, frustrations and ideas from working with the low-level details, discussing and proposing changes or new protocols to improve the situation.

From a technical standpoint, going straight to the Wayland project when finding an issue would be a bit similar to having problems with a web app and immediately pointing fingers at the HTTP spec. It is not an impossibility that the problem lies there, but it is also not a good entry point for getting an issue resolved.

It is with good intentions that you might be pointed elsewhere.