[libadwaita] doc: Add the alpha to alpha migration guide

[Adrien Plazas <aplazas src gnome org>]

commit 4c8d07bbd81771447886370bb2512b3b903e5945
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Mon Jul 19 13:42:42 2021 +0200

    doc: Add the alpha to alpha migration guide
    
    This is convenient for those who already ported to a previous alpha.

 doc/libadwaita.toml.in                        |  1 +
 doc/meson.build                               |  1 +
 doc/migrating-between-development-versions.md | 32 +++++++++++++++++++++++++++
 3 files changed, 34 insertions(+)
---
diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in
index 1dc28046..3dd101f9 100644
--- a/doc/libadwaita.toml.in
+++ b/doc/libadwaita.toml.in
@@ -39,6 +39,7 @@ file_format = "{filename}#L{line}"
 urlmap_file = "urlmap.js"
 content_files = [
   "build-howto.md",
+  "migrating-between-development-versions.md",
   "migrating-libhandy-1-4-to-libadwaita.md",
   "visual-index.md",
 ]
diff --git a/doc/meson.build b/doc/meson.build
index 29cc7ebe..e27343ba 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -2,6 +2,7 @@ if get_option('gtk_doc')
 
 expand_content_md_files = [
   'build-howto.md',
+  'migrating-between-development-versions.md',
   'migrating-libhandy-1-4-to-libadwaita.md',
   'visual-index.md',
 ]
diff --git a/doc/migrating-between-development-versions.md b/doc/migrating-between-development-versions.md
new file mode 100644
index 00000000..1acf2876
--- /dev/null
+++ b/doc/migrating-between-development-versions.md
@@ -0,0 +1,32 @@
+Title: Migrating between development versions
+Slug: migrating-between-development-versions
+
+# Migrating between development versions
+
+This guide outlines the differences between Libadwaita development releases.
+It assumes you've already migrated from Libhandy 1.4 to Libadwaita, or you
+created a new project using a development release of Libadwaita.
+
+If you want to migrate from Libhandy 1.4 to the latest Libadwaita release,
+[follow this guide](migrating-libhandy-1-4-to-libadwaita.html).
+
+## Migrating from alpha 1 to alpha 2
+
+### Adapt to view switcher API Changes
+
+[class@Adw.ViewSwitcher], [class@Adw.ViewSwitcherBar] and
+[class@Adw.ViewSwitcherTitle] now use [class@Adw.ViewStack] instead of
+[class@Gtk.Stack].
+
+You should stop using [property@Gtk.Stack:transition-type] and
+[property@Gtk.Stack:transition-duration] properties before switching to
+[class@Adw.ViewStack].
+
+### Adapt to Stylesheet Changes
+
+The public colors `@theme_selected_bg_color` and `@theme_selected_fg_color` have
+been renamed to `@accent_bg_color` and `@accent_fg_color`.
+
+If you were using `@theme_selected_bg_color` as a text color, use
+`@accent_color` instead to make sure the text is readable. You can also use the
+`.accent` style class to apply the correct color.