[gtk/matthiasc/for-main] Start a migration guide for GTK 5

[Matthias Clasen <matthiasc src gnome org>]

commit 0c94db71475df5bf709ef727f07042b9bac79ee2
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Oct 12 16:38:18 2022 -0400

    Start a migration guide for GTK 5
    
    No need to panic, GTK 5 is still years away!
    But it is good to write this material down while
    it is fresh in mind.

 docs/reference/gtk/migrating-4to5.md | 74 ++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-4to5.md b/docs/reference/gtk/migrating-4to5.md
new file mode 100644
index 0000000000..2f2b5c211a
--- /dev/null
+++ b/docs/reference/gtk/migrating-4to5.md
@@ -0,0 +1,74 @@
+Title: Preparing for GTK 5
+Slug: gtk-migrating-4-to-5
+
+GTK 5 will be a major new version of GTK that breaks both API and
+ABI compared to GTK 4.x. GTK 5 does not exist yet, so we cannot
+be entirely sure what will be involved in a migration from GTK 4
+to GTK 5. But we can already give some preliminary hints about
+the likely changes, and how to prepare for them in code that is
+using GTK 4.
+
+### Do not use deprecated symbols
+
+As always, functions and types that are known to go away in the
+next major version of GTK are being marked as deprecated in GTK 4.
+
+Removing the use of deprecated APIs is the most important step
+to prepare your code for the next major version of GTK. Often,
+deprecation notes will include hints about replacement APIs to
+help you with this.
+
+Sometimes, it is helpful to have some background information about
+the motivation and goals of larger API changes.
+
+## Cell renderers are going away
+
+Cell renderers were introduced in GTK 2 to support rendering of
+"big data" UIs, in particular treeviews. Over the years, more
+"data-like" widgets have started to use them, and cell renderers
+have grown into a shadowy, alternative rendering infrastructure
+that duplicates much of what widgets do, while duplicating the
+code and adding their own dose of bugs.
+
+In GTK 4, replacement widgets for GtkTreeView, GtkIconView and
+GtkComboBox have appeared: GtkListView, GtkColumnView, GtkGridView
+and GtkDropDown. For GTK 5, we will take the next step and remove
+all cell renderer-based widgets.
+
+## Themed rendering APIs are going away
+
+The old GTK 2 era rendering APIs for theme components like
+gtk_render_frame() or gtk_render_check() have not been used by
+GTK itself even in later GTK 3, but they have been kepy around
+for the benefit of "external drawing" users - applications that
+want their controls to look like GTK without using widgets.
+
+Supporting this is increasingly getting in the way of making
+the GTK CSS machinery fast and correct. One notable problem is
+that temporary style changes (using gtk_style_context_save())
+is breaking animations. Therefore, these APIs will be going away
+in GTK 5, together with their more modern GtkSnapshot variants
+like gtk_snapshot_render_background() or gtk_snapshot_render_focus().
+
+The best way to render parts of your widget using CSS styling
+is to use subwidgets. For example, to show a piece of text with
+fonts, effects and shadows according to the current CSS style,
+use a GtkLabel.
+
+If you have a need for custom drawing that fits into the current
+(dark or light) theme, e.g. for rendering a graph, you can still
+get the current style foreground color, using
+[method@Gtk.Widget.get_style_color].
+
+## Local stylesheets are going away
+
+The cascading part of GTK's CSS implementation is complicated by
+the existence of local stylesheets (i.e. those added with
+gtk_style_context_add_provider()). And local stylesheets are
+unintuitive in that they do not apply to the whole subtree of
+widgets, but just to the one widget where the stylesheet was
+added.
+
+GTK 5 will no longer provide this functionality. The recommendations
+is to use a global stylesheet (i.e. gtk_style_context_add_provider_for_display())
+and rely on style classes to make your CSS apply only where desired.