[libadwaita/wip/exalm/sidebars: 4/4] doc: Deprecate .sidebar

[Alexander Mikhaylenko <alexm src gnome org>]

commit 380fe3f1c632cb733060da921b2b8346cb2e976c
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Sun Oct 24 05:35:32 2021 +0500

    doc: Deprecate .sidebar
    
    Removing it turned out to be a problem, so just deprecate it instead.
    
    Since we don't have a way of properly deprecating styles, just add a
    comment and mention it in the migration guide.

 doc/migrating-between-development-versions.md | 9 +++++++++
 doc/migrating-libhandy-1-4-to-libadwaita.md   | 9 +++++++++
 src/stylesheet/widgets/_sidebars.scss         | 1 +
 3 files changed, 19 insertions(+)
---
diff --git a/doc/migrating-between-development-versions.md b/doc/migrating-between-development-versions.md
index dcf5654c..07534aad 100644
--- a/doc/migrating-between-development-versions.md
+++ b/doc/migrating-between-development-versions.md
@@ -234,3 +234,12 @@ The `adw_expander_row_add ()` function has been renamed to `adw_expander_row_add
 The `.combo` popover style class has been removed. Use `.menu` instead. You may
 need to remove manually added margins, padding or minimum height from the list
 items inside while doing it.
+
+### Stop using the `.sidebar` style class
+
+The `.sidebar` style class is now deprecated, although still works for
+compatibility reasons. The main use case - adjusting the background color of
+[class@Gtk.ListBox]` and `[class@Gtk.ListView]` - can now be done with the
+`.navigation-sidebar` style class on those widgets instead, along with adjusting
+the item selection style. The border can be replicated by manually adding a
+[class@Gtk.Separator].
diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md
index f3f2f5b3..5dfab77e 100644
--- a/doc/migrating-libhandy-1-4-to-libadwaita.md
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.md
@@ -352,6 +352,15 @@ The `.combo` popover style class has been removed. Use `.menu` instead. You may
 need to remove manually added margins, padding or minimum height from the list
 items inside while doing it.
 
+### Stop using the `.sidebar` style class
+
+The `.sidebar` style class is now deprecated, although still works for
+compatibility reasons. The main use case - adjusting the background color of
+[class@Gtk.ListBox]` and `[class@Gtk.ListView]` - can now be done with the
+`.navigation-sidebar` style class on those widgets instead, along with adjusting
+the item selection style. The border can be replicated by manually adding a
+[class@Gtk.Separator].
+
 #### Adapt to Header Bar, Action Bar, Search Bar and Toolbar Style Changes
 
 When possible, buttons in [class@Gtk.HeaderBar], [class@Gtk.ActionBar] and
diff --git a/src/stylesheet/widgets/_sidebars.scss b/src/stylesheet/widgets/_sidebars.scss
index 61d8bb20..c008c71b 100644
--- a/src/stylesheet/widgets/_sidebars.scss
+++ b/src/stylesheet/widgets/_sidebars.scss
@@ -1,3 +1,4 @@
+// Deprecated: use .navigation-sidebar instead
 .sidebar {
   &:not(separator) {
     &:dir(ltr),