Document breaking change in changelog

Author: cruessler

CHANGELOG.md

@@ -21,7 +21,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking Change
 * `focus_XYZ` key bindings are merged into the `move_XYZ` set, so only one way to bind arrow-like keys from now on ([#1539](https://github.com/extrawurst/gitui/issues/1539))
-* The format of `theme.ron` has changed
+* Do you use a custom theme?
+
+  The way themes work got changed and simplified ([see docs](https://github.com/extrawurst/gitui/blob/master/THEMES.md) for more info):
+
+  * The format of `theme.ron` has changed: you only specify the colors etc. that should differ from their default value
+  * Future additions of colors etc. will not break existing themes anymore
 
 ### Added
 * allow reset (soft,mixed,hard) from commit log ([#1500](https://github.com/extrawurst/gitui/issues/1500))

THEMES.md

@@ -3,15 +3,27 @@
 default on light terminal:
 ![](assets/light-theme.png)
 
-to change the colors of the default theme you have to modify `theme.ron` file
-[Ron format](https://github.com/ron-rs/ron) located at config path. The path differs depending on the operating system:
+To change the colors of the default theme you need to add a `theme.ron` file that contains the colors you want to override. Note that you don’t have to specify the full theme anymore (as of 0.23). Instead, it is sufficient to override just the values that you want to differ from their default values.
+
+The file uses the [Ron format](https://github.com/ron-rs/ron) and is located at one of the following paths, depending on your operating system:
 
 * `$HOME/.config/gitui/theme.ron` (mac)
 * `$XDG_CONFIG_HOME/gitui/theme.ron` (linux using XDG)
 * `$HOME/.config/gitui/theme.ron` (linux)
 * `%APPDATA%/gitui/theme.ron` (Windows)
 
-Alternatively you may make a theme in the same directory mentioned above with and select with the `-t` flag followed by the name of the file in the directory. E.g. If you are on linux calling `gitui -t arc.ron` wil use `$XDG_CONFIG_HOME/gitui/arc.ron` or `$HOME/.config/gitui/arc.ron`
+Alternatively, you can create a theme in the same directory mentioned above and use it with the `-t` flag followed by the name of the file in the directory. E.g. If you are on linux calling `gitui -t arc.ron`, this will load the theme in `$XDG_CONFIG_HOME/gitui/arc.ron` or `$HOME/.config/gitui/arc.ron`.
+
+Example theme override:
+
+```
+(
+    selection_bg: Some(Blue),
+    selection_fg: Some(White),
+)
+```
+
+Note that you need to wrap values in `Some` due to the way the overrides work (as of 0.23).
 
 Notes: