[libadwaita/wip/exalm/sidebars] stylesheet: Deprecate .sidebar

[Alexander Mikhaylenko <alexm src gnome org>]

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

    stylesheet: 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..e281525f 100644
--- a/doc/migrating-between-development-versions.md
+++ b/doc/migrating-between-development-versions.md
@@ -229,6 +229,15 @@ The `adw_expander_row_add ()` function has been renamed to `adw_expander_row_add
 
 ### Adapt to Stylesheet Changes
 
+### 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 the `popover.combo` style removal
 
 The `.combo` popover style class has been removed. Use `.menu` instead. You may
diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md
index f3f2f5b3..26602347 100644
--- a/doc/migrating-libhandy-1-4-to-libadwaita.md
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.md
@@ -346,6 +346,15 @@ 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.
 
+### 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 the `popover.combo` style removal
 
 The `.combo` popover style class has been removed. Use `.menu` instead. You may
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),