Merge pull request #1131 from swaywm/initial-stable

Initial pass on API stability guarantees

63 files changed, 559 insertions, 4 deletions

diff --git a/include/wlr/backend.h b/include/wlr/backend.h
index f40f5353..39d072e2 100644
--- a/include/wlr/backend.h
+++ b/include/wlr/backend.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_H
 #define WLR_BACKEND_H
 
diff --git a/include/wlr/backend/drm.h b/include/wlr/backend/drm.h
index 7f41ca15..a8a5525e 100644
--- a/include/wlr/backend/drm.h
+++ b/include/wlr/backend/drm.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_DRM_H
 #define WLR_BACKEND_DRM_H
 
diff --git a/include/wlr/backend/headless.h b/include/wlr/backend/headless.h
index 02c7cd11..eab102e2 100644
--- a/include/wlr/backend/headless.h
+++ b/include/wlr/backend/headless.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_HEADLESS_H
 #define WLR_BACKEND_HEADLESS_H
 
diff --git a/include/wlr/backend/interface.h b/include/wlr/backend/interface.h
index 42b39a16..f3dee69b 100644
--- a/include/wlr/backend/interface.h
+++ b/include/wlr/backend/interface.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_INTERFACE_H
 #define WLR_BACKEND_INTERFACE_H
 
diff --git a/include/wlr/backend/libinput.h b/include/wlr/backend/libinput.h
index 92d31415..1a2ab294 100644
--- a/include/wlr/backend/libinput.h
+++ b/include/wlr/backend/libinput.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_LIBINPUT_H
 #define WLR_BACKEND_LIBINPUT_H
 
diff --git a/include/wlr/backend/multi.h b/include/wlr/backend/multi.h
index 1e04dba4..7137b075 100644
--- a/include/wlr/backend/multi.h
+++ b/include/wlr/backend/multi.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_MULTI_H
 #define WLR_BACKEND_MULTI_H
 
diff --git a/include/wlr/backend/session/interface.h b/include/wlr/backend/session/interface.h
index b35ed71d..5ccf9c8a 100644
--- a/include/wlr/backend/session/interface.h
+++ b/include/wlr/backend/session/interface.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_SESSION_INTERFACE_H
 #define WLR_BACKEND_SESSION_INTERFACE_H
 
diff --git a/include/wlr/interfaces/wlr_input_device.h b/include/wlr/interfaces/wlr_input_device.h
index a5c513b7..05248bf6 100644
--- a/include/wlr/interfaces/wlr_input_device.h
+++ b/include/wlr/interfaces/wlr_input_device.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_INPUT_DEVICE_H
 #define WLR_INTERFACES_WLR_INPUT_DEVICE_H
 
diff --git a/include/wlr/interfaces/wlr_keyboard.h b/include/wlr/interfaces/wlr_keyboard.h
index c9a13fd7..5d537827 100644
--- a/include/wlr/interfaces/wlr_keyboard.h
+++ b/include/wlr/interfaces/wlr_keyboard.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_KEYBOARD_H
 #define WLR_INTERFACES_WLR_KEYBOARD_H
 
diff --git a/include/wlr/interfaces/wlr_output.h b/include/wlr/interfaces/wlr_output.h
index 8f87408a..2224932f 100644
--- a/include/wlr/interfaces/wlr_output.h
+++ b/include/wlr/interfaces/wlr_output.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_OUTPUT_H
 #define WLR_INTERFACES_WLR_OUTPUT_H
 
diff --git a/include/wlr/interfaces/wlr_pointer.h b/include/wlr/interfaces/wlr_pointer.h
index f0cf9081..fd3ab102 100644
--- a/include/wlr/interfaces/wlr_pointer.h
+++ b/include/wlr/interfaces/wlr_pointer.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_POINTER_H
 #define WLR_INTERFACES_WLR_POINTER_H
 
diff --git a/include/wlr/interfaces/wlr_tablet_pad.h b/include/wlr/interfaces/wlr_tablet_pad.h
index 5ec1e3eb..86bbe9c3 100644
--- a/include/wlr/interfaces/wlr_tablet_pad.h
+++ b/include/wlr/interfaces/wlr_tablet_pad.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_TABLET_PAD_H
 #define WLR_INTERFACES_WLR_TABLET_PAD_H
 
diff --git a/include/wlr/interfaces/wlr_tablet_tool.h b/include/wlr/interfaces/wlr_tablet_tool.h
index 12b2e32e..9cfc3ca0 100644
--- a/include/wlr/interfaces/wlr_tablet_tool.h
+++ b/include/wlr/interfaces/wlr_tablet_tool.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_TABLET_TOOL_H
 #define WLR_INTERFACES_WLR_TABLET_TOOL_H
 
diff --git a/include/wlr/interfaces/wlr_touch.h b/include/wlr/interfaces/wlr_touch.h
index 63bac6b8..cc426332 100644
--- a/include/wlr/interfaces/wlr_touch.h
+++ b/include/wlr/interfaces/wlr_touch.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_TOUCH_H
 #define WLR_INTERFACES_WLR_TOUCH_H
 
diff --git a/include/wlr/render/dmabuf.h b/include/wlr/render/dmabuf.h
index 78f8c2eb..33c3a129 100644
--- a/include/wlr/render/dmabuf.h
+++ b/include/wlr/render/dmabuf.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_DMABUF_H
 #define WLR_RENDER_DMABUF_H
 
diff --git a/include/wlr/render/egl.h b/include/wlr/render/egl.h
index 6b887f4f..c42b0325 100644
--- a/include/wlr/render/egl.h
+++ b/include/wlr/render/egl.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_EGL_H
 #define WLR_RENDER_EGL_H
 
diff --git a/include/wlr/render/gles2.h b/include/wlr/render/gles2.h
index 866c6658..fca11ab8 100644
--- a/include/wlr/render/gles2.h
+++ b/include/wlr/render/gles2.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_GLES2_H
 #define WLR_RENDER_GLES2_H
 
diff --git a/include/wlr/render/interface.h b/include/wlr/render/interface.h
index f4565ad5..63f4265c 100644
--- a/include/wlr/render/interface.h
+++ b/include/wlr/render/interface.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_INTERFACE_H
 #define WLR_RENDER_INTERFACE_H
 
diff --git a/include/wlr/render/wlr_renderer.h b/include/wlr/render/wlr_renderer.h
index 0650bf1b..9c031b7f 100644
--- a/include/wlr/render/wlr_renderer.h
+++ b/include/wlr/render/wlr_renderer.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_WLR_RENDERER_H
 #define WLR_RENDER_WLR_RENDERER_H
 
diff --git a/include/wlr/render/wlr_texture.h b/include/wlr/render/wlr_texture.h
index 9370fa25..dbfabfee 100644
--- a/include/wlr/render/wlr_texture.h
+++ b/include/wlr/render/wlr_texture.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_WLR_TEXTURE_H
 #define WLR_RENDER_WLR_TEXTURE_H
 
diff --git a/include/wlr/types/wlr_box.h b/include/wlr/types/wlr_box.h
index 0e586a18..11a53b56 100644
--- a/include/wlr/types/wlr_box.h
+++ b/include/wlr/types/wlr_box.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_BOX_H
 #define WLR_TYPES_WLR_BOX_H
 
diff --git a/include/wlr/types/wlr_buffer.h b/include/wlr/types/wlr_buffer.h
index eabc8b51..0c987b17 100644
--- a/include/wlr/types/wlr_buffer.h
+++ b/include/wlr/types/wlr_buffer.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_BUFFER_H
 #define WLR_TYPES_WLR_BUFFER_H
 
diff --git a/include/wlr/types/wlr_compositor.h b/include/wlr/types/wlr_compositor.h
index 0d79b0bb..1772e54b 100644
--- a/include/wlr/types/wlr_compositor.h
+++ b/include/wlr/types/wlr_compositor.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_COMPOSITOR_H
 #define WLR_TYPES_WLR_COMPOSITOR_H
 
diff --git a/include/wlr/types/wlr_cursor.h b/include/wlr/types/wlr_cursor.h
index 998c6f0d..ba582be9 100644
--- a/include/wlr/types/wlr_cursor.h
+++ b/include/wlr/types/wlr_cursor.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_CURSOR_H
 #define WLR_TYPES_WLR_CURSOR_H
 
diff --git a/include/wlr/types/wlr_data_device.h b/include/wlr/types/wlr_data_device.h
index 8b7b374c..cc04c9e9 100644
--- a/include/wlr/types/wlr_data_device.h
+++ b/include/wlr/types/wlr_data_device.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_DATA_DEVICE_H
 #define WLR_TYPES_WLR_DATA_DEVICE_H
 
diff --git a/include/wlr/types/wlr_export_dmabuf_v1.h b/include/wlr/types/wlr_export_dmabuf_v1.h
index a094b3de..56767540 100644
--- a/include/wlr/types/wlr_export_dmabuf_v1.h
+++ b/include/wlr/types/wlr_export_dmabuf_v1.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_EXPORT_DMABUF_V1_H
 #define WLR_TYPES_WLR_EXPORT_DMABUF_V1_H
 
diff --git a/include/wlr/types/wlr_gamma_control.h b/include/wlr/types/wlr_gamma_control.h
index f195c8ef..ac078b5a 100644
--- a/include/wlr/types/wlr_gamma_control.h
+++ b/include/wlr/types/wlr_gamma_control.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_GAMMA_CONTROL_H
 #define WLR_TYPES_WLR_GAMMA_CONTROL_H
 
diff --git a/include/wlr/types/wlr_idle.h b/include/wlr/types/wlr_idle.h
index 53fc6b98..608b5894 100644
--- a/include/wlr/types/wlr_idle.h
+++ b/include/wlr/types/wlr_idle.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_IDLE_H
 #define WLR_TYPES_WLR_IDLE_H
 
diff --git a/include/wlr/types/wlr_idle_inhibit_v1.h b/include/wlr/types/wlr_idle_inhibit_v1.h
index 011abbe5..9f481e2f 100644
--- a/include/wlr/types/wlr_idle_inhibit_v1.h
+++ b/include/wlr/types/wlr_idle_inhibit_v1.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_IDLE_INHIBIT_V1_H
 #define WLR_TYPES_WLR_IDLE_INHIBIT_V1_H
 
@@ -19,7 +27,7 @@ struct wlr_idle_inhibit_manager_v1 {
 	struct wl_list resources; // wl_resource_get_link
 	struct wl_list inhibitors; // wlr_idle_inhibit_inhibitor_v1::link
 	struct wl_global *global;
-	
+
 	struct wl_listener display_destroy;
 
 	struct {
diff --git a/include/wlr/types/wlr_input_device.h b/include/wlr/types/wlr_input_device.h
index cce15d90..ab0aecb6 100644
--- a/include/wlr/types/wlr_input_device.h
+++ b/include/wlr/types/wlr_input_device.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_INPUT_DEVICE_H
 #define WLR_TYPES_WLR_INPUT_DEVICE_H
 
diff --git a/include/wlr/types/wlr_input_inhibitor.h b/include/wlr/types/wlr_input_inhibitor.h
index 2f333f3b..5772f1a5 100644
--- a/include/wlr/types/wlr_input_inhibitor.h
+++ b/include/wlr/types/wlr_input_inhibitor.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_INPUT_INHIBITOR_H
 #define WLR_TYPES_INPUT_INHIBITOR_H
 #include <wayland-server.h>
diff --git a/include/wlr/types/wlr_keyboard.h b/include/wlr/types/wlr_keyboard.h
index 67d4e5be..3e207523 100644
--- a/include/wlr/types/wlr_keyboard.h
+++ b/include/wlr/types/wlr_keyboard.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_KEYBOARD_H
 #define WLR_TYPES_WLR_KEYBOARD_H
 
diff --git a/include/wlr/types/wlr_layer_shell.h b/include/wlr/types/wlr_layer_shell.h
index 2848a115..029f8cbe 100644
--- a/include/wlr/types/wlr_layer_shell.h
+++ b/include/wlr/types/wlr_layer_shell.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_LAYER_SHELL_H
 #define WLR_TYPES_WLR_LAYER_SHELL_H
 #include <stdbool.h>
diff --git a/include/wlr/types/wlr_linux_dmabuf_v1.h b/include/wlr/types/wlr_linux_dmabuf_v1.h
index 43bc8385..f21b0b3a 100644
--- a/include/wlr/types/wlr_linux_dmabuf_v1.h
+++ b/include/wlr/types/wlr_linux_dmabuf_v1.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_LINUX_DMABUF_H
 #define WLR_TYPES_WLR_LINUX_DMABUF_H
 
diff --git a/include/wlr/types/wlr_list.h b/include/wlr/types/wlr_list.h
index 23bf53b7..60f388f9 100644
--- a/include/wlr/types/wlr_list.h
+++ b/include/wlr/types/wlr_list.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_LIST_H
 #define WLR_TYPES_WLR_LIST_H
 
diff --git a/include/wlr/types/wlr_matrix.h b/include/wlr/types/wlr_matrix.h
index 02111db8..a3961c35 100644
--- a/include/wlr/types/wlr_matrix.h
+++ b/include/wlr/types/wlr_matrix.h
@@ -1,20 +1,57 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_TYPES_WLR_MATRIX_H
 #define WLR_TYPES_WLR_MATRIX_H
 
 #include <wayland-server.h>
 #include <wlr/types/wlr_box.h>
 
+/** Writes the identity matrix into mat */
 void wlr_matrix_identity(float mat[static 9]);
+
+/** mat ← a × b */
 void wlr_matrix_multiply(float mat[static 9], const float a[static 9],
 	const float b[static 9]);
+
 void wlr_matrix_transpose(float mat[static 9], const float a[static 9]);
+
+/** Writes a 2D translation matrix to mat of magnitude (x, y) */
 void wlr_matrix_translate(float mat[static 9], float x, float y);
+
+/** Writes a 2D scale matrix to mat of magnitude (x, y) */
 void wlr_matrix_scale(float mat[static 9], float x, float y);
+
+/** Writes a 2D rotation matrix to mat at an angle of rad radians */
 void wlr_matrix_rotate(float mat[static 9], float rad);
+
+/** Writes a transformation matrix which applies the specified
+ *  wl_output_transform to mat */
 void wlr_matrix_transform(float mat[static 9],
 	enum wl_output_transform transform);
+
+/** Writes a 2D orthographic projection matrix to mat of (width, height) with a
+ *  specified wl_output_transform*/
 void wlr_matrix_projection(float mat[static 9], int width, int height,
 	enum wl_output_transform transform);
+
+/** Shortcut for the various matrix operations involved in projecting the
+ *  specified wlr_box onto a given orthographic projection with a given
+ *  rotation. The result is written to mat, which can be applied to each
+ *  coordinate of the box to get a new coordinate from [-1,1]. */
 void wlr_matrix_project_box(float mat[static 9], const struct wlr_box *box,
 	enum wl_output_transform transform, float rotation,
 	const float projection[static 9]);
diff --git a/include/wlr/types/wlr_output.h b/include/wlr/types/wlr_output.h
index c93ed2eb..f8452d12 100644
--- a/include/wlr/types/wlr_output.h
+++ b/include/wlr/types/wlr_output.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_OUTPUT_H
 #define WLR_TYPES_WLR_OUTPUT_H
 
diff --git a/include/wlr/types/wlr_output_damage.h b/include/wlr/types/wlr_output_damage.h
index a4333c1a..d614e6d6 100644
--- a/include/wlr/types/wlr_output_damage.h
+++ b/include/wlr/types/wlr_output_damage.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_OUTPUT_DAMAGE_H
 #define WLR_TYPES_WLR_OUTPUT_DAMAGE_H
 
diff --git a/include/wlr/types/wlr_output_layout.h b/include/wlr/types/wlr_output_layout.h
index 759c8ccf..2ac12a6a 100644
--- a/include/wlr/types/wlr_output_layout.h
+++ b/include/wlr/types/wlr_output_layout.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_OUTPUT_LAYOUT_H
 #define WLR_TYPES_WLR_OUTPUT_LAYOUT_H
 
diff --git a/include/wlr/types/wlr_pointer.h b/include/wlr/types/wlr_pointer.h
index 48c89151..7dc643ae 100644
--- a/include/wlr/types/wlr_pointer.h
+++ b/include/wlr/types/wlr_pointer.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_POINTER_H
 #define WLR_TYPES_WLR_POINTER_H
 
diff --git a/include/wlr/types/wlr_primary_selection.h b/include/wlr/types/wlr_primary_selection.h
index 78f23ad6..fa9ee843 100644
--- a/include/wlr/types/wlr_primary_selection.h
+++ b/include/wlr/types/wlr_primary_selection.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_PRIMARY_SELECTION_H
 #define WLR_TYPES_WLR_PRIMARY_SELECTION_H
 
diff --git a/include/wlr/types/wlr_region.h b/include/wlr/types/wlr_region.h
index be2f8b84..3c4a0532 100644
--- a/include/wlr/types/wlr_region.h
+++ b/include/wlr/types/wlr_region.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_REGION_H
 #define WLR_TYPES_WLR_REGION_H
 
diff --git a/include/wlr/types/wlr_screencopy_v1.h b/include/wlr/types/wlr_screencopy_v1.h
index 892687aa..8c3b77fd 100644
--- a/include/wlr/types/wlr_screencopy_v1.h
+++ b/include/wlr/types/wlr_screencopy_v1.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SCREENCOPY_V1_H
 #define WLR_TYPES_WLR_SCREENCOPY_V1_H
 
diff --git a/include/wlr/types/wlr_screenshooter.h b/include/wlr/types/wlr_screenshooter.h
index 916c8942..ccdb8cf5 100644
--- a/include/wlr/types/wlr_screenshooter.h
+++ b/include/wlr/types/wlr_screenshooter.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SCREENSHOOTER_H
 #define WLR_TYPES_WLR_SCREENSHOOTER_H
 
diff --git a/include/wlr/types/wlr_seat.h b/include/wlr/types/wlr_seat.h
index 92d0a233..b3c02cf2 100644
--- a/include/wlr/types/wlr_seat.h
+++ b/include/wlr/types/wlr_seat.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SEAT_H
 #define WLR_TYPES_WLR_SEAT_H
 
diff --git a/include/wlr/types/wlr_server_decoration.h b/include/wlr/types/wlr_server_decoration.h
index 23387968..2a76b35c 100644
--- a/include/wlr/types/wlr_server_decoration.h
+++ b/include/wlr/types/wlr_server_decoration.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SERVER_DECORATION_H
 #define WLR_TYPES_WLR_SERVER_DECORATION_H
 
diff --git a/include/wlr/types/wlr_surface.h b/include/wlr/types/wlr_surface.h
index ee9afa86..063f9e26 100644
--- a/include/wlr/types/wlr_surface.h
+++ b/include/wlr/types/wlr_surface.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SURFACE_H
 #define WLR_TYPES_WLR_SURFACE_H
 
diff --git a/include/wlr/types/wlr_tablet_pad.h b/include/wlr/types/wlr_tablet_pad.h
index 23ac464d..d9bb284f 100644
--- a/include/wlr/types/wlr_tablet_pad.h
+++ b/include/wlr/types/wlr_tablet_pad.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_TABLET_PAD_H
 #define WLR_TYPES_WLR_TABLET_PAD_H
 
diff --git a/include/wlr/types/wlr_tablet_tool.h b/include/wlr/types/wlr_tablet_tool.h
index bfa2e1f7..cb516ed9 100644
--- a/include/wlr/types/wlr_tablet_tool.h
+++ b/include/wlr/types/wlr_tablet_tool.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_TABLET_TOOL_H
 #define WLR_TYPES_TABLET_TOOL_H
 
diff --git a/include/wlr/types/wlr_tablet_v2.h b/include/wlr/types/wlr_tablet_v2.h
index afa74d05..c332b5b1 100644
--- a/include/wlr/types/wlr_tablet_v2.h
+++ b/include/wlr/types/wlr_tablet_v2.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_TABLET_V2_H
 #define WLR_TYPES_WLR_TABLET_V2_H
 
diff --git a/include/wlr/types/wlr_touch.h b/include/wlr/types/wlr_touch.h
index 70070f84..99316ae0 100644
--- a/include/wlr/types/wlr_touch.h
+++ b/include/wlr/types/wlr_touch.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_TOUCH_H
 #define WLR_TYPES_WLR_TOUCH_H
 
diff --git a/include/wlr/types/wlr_virtual_keyboard_v1.h b/include/wlr/types/wlr_virtual_keyboard_v1.h
index 1236ae24..1df0f3a3 100644
--- a/include/wlr/types/wlr_virtual_keyboard_v1.h
+++ b/include/wlr/types/wlr_virtual_keyboard_v1.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_VIRTUAL_KEYBOARD_V1_H
 #define WLR_TYPES_WLR_VIRTUAL_KEYBOARD_V1_H
 
diff --git a/include/wlr/types/wlr_wl_shell.h b/include/wlr/types/wlr_wl_shell.h
index c4cc1999..0a52ae3e 100644
--- a/include/wlr/types/wlr_wl_shell.h
+++ b/include/wlr/types/wlr_wl_shell.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_WL_SHELL_H
 #define WLR_TYPES_WLR_WL_SHELL_H
 
diff --git a/include/wlr/types/wlr_xcursor_manager.h b/include/wlr/types/wlr_xcursor_manager.h
index c7fa83be..285006bf 100644
--- a/include/wlr/types/wlr_xcursor_manager.h
+++ b/include/wlr/types/wlr_xcursor_manager.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XCURSOR_MANAGER_H
 #define WLR_TYPES_WLR_XCURSOR_MANAGER_H
 
diff --git a/include/wlr/types/wlr_xdg_output.h b/include/wlr/types/wlr_xdg_output.h
index 81566ab9..2754b291 100644
--- a/include/wlr/types/wlr_xdg_output.h
+++ b/include/wlr/types/wlr_xdg_output.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XDG_OUTPUT_H
 #define WLR_TYPES_WLR_XDG_OUTPUT_H
 #include <wayland-server.h>
diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h
index 5aa6b374..98538e7f 100644
--- a/include/wlr/types/wlr_xdg_shell.h
+++ b/include/wlr/types/wlr_xdg_shell.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XDG_SHELL_H
 #define WLR_TYPES_WLR_XDG_SHELL_H
 #include <wlr/types/wlr_box.h>
diff --git a/include/wlr/types/wlr_xdg_shell_v6.h b/include/wlr/types/wlr_xdg_shell_v6.h
index 2357d945..8fdf5090 100644
--- a/include/wlr/types/wlr_xdg_shell_v6.h
+++ b/include/wlr/types/wlr_xdg_shell_v6.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XDG_SHELL_V6_H
 #define WLR_TYPES_WLR_XDG_SHELL_V6_H
 
diff --git a/include/wlr/util/edges.h b/include/wlr/util/edges.h
index 53268323..bf1eb1e7 100644
--- a/include/wlr/util/edges.h
+++ b/include/wlr/util/edges.h
@@ -1,3 +1,19 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_UTIL_EDGES_H
 #define WLR_UTIL_EDGES_H
 
diff --git a/include/wlr/util/log.h b/include/wlr/util/log.h
index 098a020d..7b0070bb 100644
--- a/include/wlr/util/log.h
+++ b/include/wlr/util/log.h
@@ -1,3 +1,19 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_UTIL_LOG_H
 #define WLR_UTIL_LOG_H
 
diff --git a/include/wlr/util/region.h b/include/wlr/util/region.h
index c0fe6063..32387bfb 100644
--- a/include/wlr/util/region.h
+++ b/include/wlr/util/region.h
@@ -1,6 +1,21 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_UTIL_REGION_H
 #define WLR_UTIL_REGION_H
-
 #include <pixman.h>
 #include <wayland-server.h>
 
diff --git a/include/wlr/xcursor.h b/include/wlr/xcursor.h
index d97469f8..39874f39 100644
--- a/include/wlr/xcursor.h
+++ b/include/wlr/xcursor.h
@@ -24,8 +24,19 @@
  */
 
 /*
- * This is adapted from wayland-cursor, but with the wl_shm client stuff removed
- * so we can use it on the compositor, too.
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
  */
 
 #ifndef WLR_XCURSOR_H
diff --git a/include/wlr/xwayland.h b/include/wlr/xwayland.h
index e7f7a467..39644dc1 100644
--- a/include/wlr/xwayland.h
+++ b/include/wlr/xwayland.h
@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_XWAYLAND_H
 #define WLR_XWAYLAND_H
 
diff --git a/meson.build b/meson.build
index 5fd89832..6b401597 100644
--- a/meson.build
+++ b/meson.build
@@ -29,6 +29,10 @@ add_project_link_arguments(
 	'-Wl,-rpath,@0@'.format(meson.build_root()),
 	language: 'c',
 )
+add_project_arguments(
+	'-DWLR_USE_UNSTABLE',
+	language: 'c',
+)
 
 conf_data = configuration_data()