diff --git a/glfw/wl_window.c b/glfw/wl_window.c
index 372bf9052..73c06e41a 100644
--- a/glfw/wl_window.c
+++ b/glfw/wl_window.c
@@ -588,6 +588,12 @@ static void xdgSurfaceHandleConfigure(void* data,
                                       struct xdg_surface* surface,
                                       uint32_t serial)
 {
+    // The poorly documented pattern Wayland requires ack the configure,
+    // set the window geometry attach a new buffer of the correct size to the surface
+    // and only then commit the surface. buffer is attached only by eglSwapBuffers,
+    // so we set a flag to not commit the surface till the next swapbuffers. Note that
+    // wl_egl_window_resize() does not actually resize the buffer until the next draw call
+    // or buffer state query.
     _GLFWwindow* window = data;
     xdg_surface_ack_configure(surface, serial);
     if (window->wl.pending_state & PENDING_STATE_TOPLEVEL) {