[gtk/matthiasc/for-master: 8/8] Mention icon theme in the migration guide

[Matthias Clasen <matthiasc src gnome org>]

commit 5fa765b28447797465b4e6b731fa799e834cc978
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Sep 30 08:49:42 2020 -0400

    Mention icon theme in the migration guide
    
    This was requested in #3216.

 docs/reference/gtk/migrating-3to4.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md
index bae17df96f..429e7c7421 100644
--- a/docs/reference/gtk/migrating-3to4.md
+++ b/docs/reference/gtk/migrating-3to4.md
@@ -220,6 +220,18 @@ replace many uses of gtk_container_add() with equivalent container-specific
 APIs such as gtk_box_pack_start() or gtk_grid_attach(), and thereby reduce
 the amount of work you have to do at the time of the switch.
 
+### Review your use of icon resources
+
+When using icons as resources, the behavior of GTK 4 is different in one
+respect: Icons that are directly in $APP_ID/icons/ are treated as unthemed
+icons, which also means that symbolic icons are not recolored. If you want
+your icon resources to have icon theme semantics, they need to be placed
+into theme subdirectories such as $APP_ID/icons/16x16/actions or
+$APP_ID/icons/scalable/status.
+
+This location works fine in GTK 3 too, so you can prepare for this change
+before switching to GTK 4.
+
 ## Changes that need to be done at the time of the switch
 
 This section outlines porting tasks that you need to tackle when