diff --git a/docs/reference/gtk/migrating-3xtoy.xml b/docs/reference/gtk/migrating-3xtoy.xml
index 1040c1234a..deb73d544b 100644
--- a/docs/reference/gtk/migrating-3xtoy.xml
+++ b/docs/reference/gtk/migrating-3xtoy.xml
@@ -438,6 +438,15 @@
       The behavior of the expand flag in #GtkTables #GtkAttachOptions has been
        changed to (again) match the behavior in #GtkBox and in GTK+ 2.x. These
        options don't cause the table itself to expand.
-    </para>
+     </para>
+
+     <para>
+       The way GtkPopover behaved during a call to gtk_widget_hide() violated
+       some of the internal assumptions GTK+ makes about widget visibility.
+       gtk_popover_popup() and gtk_popover_popdown() have been introduced to
+       show or hide the popover with a transition, while gtk_widget_show()
+       and gtk_widget_hide() on a GtkPopover now work the same way they do
+       on any other widget and immediately hide (or show) the popover.
+     </para>
   </section>
 </chapter>
diff --git a/gtk/gtkpopover.c b/gtk/gtkpopover.c
index 48be0efafa..7aa4bb41f8 100644
--- a/gtk/gtkpopover.c
+++ b/gtk/gtkpopover.c
@@ -243,8 +243,10 @@ gtk_popover_set_property (GObject      *object,
                              g_value_get_boolean (value));
       break;
     case PROP_TRANSITIONS_ENABLED:
+      G_GNUC_BEGIN_IGNORE_DEPRECATIONS;
       gtk_popover_set_transitions_enabled (GTK_POPOVER (object),
                                            g_value_get_boolean (value));
+      G_GNUC_END_IGNORE_DEPRECATIONS;
       break;
     case PROP_CONSTRAIN_TO:
       gtk_popover_set_constrain_to (GTK_POPOVER (object),
@@ -1743,7 +1745,7 @@ gtk_popover_class_init (GtkPopoverClass *klass)
                             P_("Transitions enabled"),
                             P_("Whether show/hide transitions are enabled or not"),
                             TRUE,
-                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY|G_PARAM_DEPRECATED);
 
   /**
    * GtkPopover:constrain-to:
@@ -2334,6 +2336,9 @@ gtk_popover_get_modal (GtkPopover *popover)
  * Sets whether show/hide transitions are enabled on this popover
  *
  * Since: 3.16
+ *
+ * Deprecated: 3.22: You can show or hide the popover without transitions
+ *   using gtk_widget_show() and gtk_widget_hide().
  */
 void
 gtk_popover_set_transitions_enabled (GtkPopover *popover,
@@ -2362,6 +2367,9 @@ gtk_popover_set_transitions_enabled (GtkPopover *popover,
  *          popover are enabled, #FALSE otherwise.
  *
  * Since: 3.16
+ *
+ * Deprecated: 3.22: You can show or hide the popover without transitions
+ *   using gtk_widget_show() and gtk_widget_hide().
  */
 gboolean
 gtk_popover_get_transitions_enabled (GtkPopover *popover)
diff --git a/gtk/gtkpopover.h b/gtk/gtkpopover.h
index af8359c59e..becdfb202b 100644
--- a/gtk/gtkpopover.h
+++ b/gtk/gtkpopover.h
@@ -97,10 +97,10 @@ void            gtk_popover_bind_model      (GtkPopover            *popover,
                                              GMenuModel            *model,
                                              const gchar           *action_namespace);
 
-GDK_AVAILABLE_IN_3_16
+GDK_DEPRECATED_IN_3_22
 void            gtk_popover_set_transitions_enabled (GtkPopover *popover,
                                                      gboolean    transitions_enabled);
-GDK_AVAILABLE_IN_3_16
+GDK_DEPRECATED_IN_3_22
 gboolean        gtk_popover_get_transitions_enabled (GtkPopover *popover);
 
 GDK_AVAILABLE_IN_3_18