diff --git a/doc/migrating-between-development-versions.md b/doc/migrating-between-development-versions.md
index e281525f86d703890df1a3c11e95583411c4f4e6..df8b8e081e0f73b04322f1229b6a966daeb18a22 100644
--- a/doc/migrating-between-development-versions.md
+++ b/doc/migrating-between-development-versions.md
@@ -227,6 +227,11 @@ The title and subtitle have markup enabled, make sure to escape it with
 
 The `adw_expander_row_add ()` function has been renamed to `adw_expander_row_add_row ()`.
 
+### Adjusting Header Bar Icons
+
+If you're using the `object-select-symbolic` icon in a header bar button
+(typically for selection mode), use `selection-mode-symbolic` instead.
+
 ### Adapt to Stylesheet Changes
 
 ### Stop using the `.sidebar` style class
diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md
index 26602347c0575c35aff826f592f57dbad249661a..3aa71b8a49f5ed6c4cab2c48b8a2477f91c147c4 100644
--- a/doc/migrating-libhandy-1-4-to-libadwaita.md
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.md
@@ -394,6 +394,15 @@ style.
 The same rules are also used for the `.toolbar` style class now, instead of
 making every button appear flat.
 
+#### Adjusting Icons
+
+If you're bundling icons from the icon library with your application, make sure
+to update them. Many icons have been redrawn to be larger to work better without
+button frames.
+
+If you're using the `object-select-symbolic` icon in a header bar button
+(typically for selection mode), use `selection-mode-symbolic` instead.
+
 #### Adjusting Icon+Arrow Menu Buttons
 
 If you had menu buttons containing an icon and a dropdown arrow, switch to