diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 8082a5499e..7a98b821c7 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -6192,8 +6192,14 @@ id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
 
         <para>
             You must explicitly mark post installs to defer to the target.
-            Warnings in the previous Yocto Project releases have become
-            errors.
+            If you want to explicitly defer a postinstall to first boot on
+            the target rather than at rootfs creation time, use
+            <filename>pkg_postinst_ontarget()</filename> or call
+            <filename>postinst-intercepts defer_to_first_boot</filename> from
+            <filename>pkg_postinst()</filename>.
+            Any failure of a <filename>pkg_postinst()</filename> script
+            (including exit 1) triggers an error during the
+            <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> task.
         </para>
     </section>