diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index b599421d68..c5e9ef148c 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -305,6 +305,21 @@
       </para>
     </section>
 
+    <section>
+      <title>Stop using GtkButtonBox</title>
+      <para>
+        GtkButtonBox has been removed. Use a GtkBox instead.
+      </para>
+    </section>
+
+    <section>
+      <title>Adapt to GtkButton API changes</title>
+      <para>
+        GtkBox no longer has pack-start and -end. Pack your widgets in the 
+        correct order, or reorder them as necessary.
+      </para>
+    </section>
+
     <section>
       <title>Adapt to GtkHeaderBar API changes</title>
       <para>