The way theming works in GTK+ has been reworked fundamentally, to implement many more CSS features and make themes more expressive. As a result, custom CSS that is shipped with applications and third-party themes will need adjustments. Widgets now use element names much more than style classes; type names are no longer used in style matching. Every widget now documents the element names it has and the style classes it uses. The GTK+ inspector can also help with finding this information.
GTK+ now uses internal subobjects (also known as gadgets) for allocating and drawing widget parts. Applications that subclass GTK+ widgets may see warnings if they override the size_allocate vfunc and don't chain up. The proper way to subclass is to chain up in size_allocate. If you do not want to do that for some reason, you have to override the draw vfunc as well.
Several fixes for window sizing and window placement with client-side
decorations may affect applications that are saving and restoring window
sizes. The recommended best practice for this which is known to work with
client-side and server-side decorations and with older and newer versions
of GTK+ is to use
gtk_window_get_size() to save window sizes and
gtk_window_set_default_size() to restore it.
See https://wiki.gnome.org/HowDoI/SaveWindowState for a detailed example.
Geometry handling in GtkWindow has been removed. If you are using the functions gtk_window_resize_to_geometry, gtk_window_set_default_geometry, gtk_window_parse_geometry or gtk_window_set_geometry_hints, you may need to make some changes to your code.
GtkDrawingArea used to implicitly render the theme background before
calling the ::draw handler. This is no longer the case. If you rely
on having a theme-provided background, call
from your ::draw handler.
The GtkFileChooser interface prerequisite changed from GtkWidget to GObject, allowing non-widget implementations of this interface. This is a minor change in ABI, as applications are no longer guaranteed that a GtkFileChooser also supports all GtkWidget methods. However, all previously existing implementations still derive from GtkWidget, so no existing code should break.
The way in which GtkLevelBar determines the offset to apply was a bit inconsistent in the past; this has been fixed. Applications that are using custom offsets should double-check that their levels look as expected.