[gtk/wip/exalm/headerbar-migration] docs: Mention GtkHeaderBar title and subtitle changes in migration guide

[Alexander Mikhaylenko <alexm src gnome org>]

commit 3634f4592cb4ff7709516221954353bb3c2d70ae
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Thu May 14 18:53:09 2020 +0500

    docs: Mention GtkHeaderBar title and subtitle changes in migration guide

 docs/reference/gtk/migrating-3to4.xml | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index 0503bf0e13..b8f8aeda10 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -535,6 +535,34 @@
         the more accurate name gtk_header_bar_set_show_title_buttons(). The
         corresponding getter and the property itself have also been renamed.
       </para>
+      <para>
+        The gtk_header_bar_set_custom_title() function has been renamed to
+        the more accurate name gtk_header_bar_set_title_widget(). The
+        corresponding getter and the property itself have also been renamed.
+      </para>
+      <para>
+        The gtk_header_bar_set_title() function has been removed along with its
+        corresponding getter and the property. By default GtkHeaderBar shows the
+        title of the window, so if you were consider setting the window title
+        instead. If you need to show a title that's different from the window
+        title, use "title-widget" property to add a GtkLabel as shown in the
+        example in #GtkHeaderBar documentation.
+      </para>
+      <para>
+        The gtk_header_bar_set_subtitle() function has been removed along with
+        its corresponding getter and the property. Subtitle can be replicated
+        by setting "title-widget" property to a GtkBox with two labels inside,
+        with the title label matching the example in #GtkHeaderBar
+        documentation, and the subtitle label being similar, but with "subtitle"
+        style class instead of "title".
+      </para>
+      <para>
+        The gtk_header_bar_set_has_subtitle() function has been removed along
+        with its corresponding getter and the property. Its behavior can be
+        replicated "title-widget" property to a GtkStack with "vhomogeneous"
+        property set to %TRUE, with two pages each with a GtkBox with title
+        and subtitle as described above.
+      </para>
       <para>
         The ::pack-type child properties of GtkHeaderBar and GtkActionBar have
         been removed. If you need to programmatically place children, use the