docs: add BREAKING-CHANGES.md (#538)

Document the breaking changes in each version. This document is
manually curated by summarizing the breaking changes in the changelog.

BREAKING-CHANGES.md

@@ -0,0 +1,200 @@
+# Breaking Changes
+
+This document contains a list of breaking changes in each version and some notes to help migrate
+between versions. It is compile manually from the commit history and changelog. We also tag PRs on
+github with a [breaking change] label.
+
+[breaking change]: (https://github.com/ratatui-org/ratatui/issues?q=label%3A%22breaking+change%22)
+
+## Unreleased (0.24.0)
+
+### ScrollbarState field type changed from `u16` to `usize` ([#456])
+
+[#456]: https://github.com/ratatui-org/ratatui/pull/456
+
+In order to support larger content lengths, the `position`, `content_length` and
+`viewport_content_length` methods on `ScrollbarState` now take `usize` instead of `u16`
+
+### `BorderType::line_symbols` renamed to `border_symbols` ([#529])
+
+[#529]: https://github.com/ratatui-org/ratatui/issues/529
+
+Applications can now set custom borders on a `Block` by calling `border_set()`. The
+`BorderType::line_symbols()` is renamed to `border_symbols()` and now returns a new struct
+`symbols::border::Set`. E.g.:
+
+```rust
+let line_set: symbols::line::Set = BorderType::line_symbols(BorderType::Plain);
+// becomes
+let border_set: symbols::border::Set = BorderType::border_symbols(BorderType::Plain);
+```
+
+### Generic `Backend` parameter removed from `Frame` ([#530])
+
+[#530]: https://github.com/ratatui-org/ratatui/issues/530
+
+`Frame` is no longer generic over Backend. Code that accepted `Frame<Backend>` will now need to
+accept `Frame`. To migrate existing code, remove any generic parameters from code that uses an
+instance of a Frame. E.g.:
+
+```rust
+fn ui<B: Backend>(frame: &mut Frame<B>) { ... }
+// becomes
+fn ui(frame: Frame) { ... }
+```
+
+### `Stylize` shorthands now consume rather than borrow `String` ([#466])
+
+[#466]: https://github.com/ratatui-org/ratatui/issues/466
+
+In order to support using `Stylize` shorthands (e.g. `"foo".red()`) on temporary `String` values, a
+new implementation of `Stylize` was added that returns a `Span<'static>`. This causes the value to
+be consumed rather than borrowed. Existing code that expects to use the string after a call will no
+longer compile. E.g.
+
+```rust
+let s = String::new("foo");
+let span1 = s.red();
+let span2 = s.blue(); // will no longer compile as s is consumed by the previous line
+// becomes
+let span1 = s.clone().red();
+let span2 = s.blue();
+```
+
+### Deprecated `Spans` type removed (replaced with `Line`) ([#426])
+
+[#426]: https://github.com/ratatui-org/ratatui/issues/426
+
+`Spans` was replaced with `Line` in 0.21.0. `Buffer::set_spans` was replaced with
+`Buffer::set_line`.
+
+```rust
+let spans = Spans::from(some_string_str_span_or_vec_span);
+buffer.set_spans(0, 0, spans, 10);
+// becomes
+let line - Line::from(some_string_str_span_or_vec_span);
+buffer.set_line(0, 0, line, 10);
+```
+
+## [v0.23.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.23.0)
+
+### `Scrollbar::track_symbol()` now takes an `Option<&str>` instead of `&str` ([#360])
+
+[#360]: https://github.com/ratatui-org/ratatui/issues/360
+
+The track symbol of `Scrollbar` is now optional, this method now takes an optional value.
+
+```rust
+let scrollbar = Scrollbar::default().track_symbol("|");
+// becomes
+let scrollbar = Scrollbar::default().track_symbol(Some("|"));
+```
+
+### `Scrollbar` symbols moved to `symbols::scrollbar` and `widgets::scrollbar` module is private ([#330])
+
+[#330]: https://github.com/ratatui-org/ratatui/issues/330
+
+The symbols for defining scrollbars have been moved to the `symbols` module from the
+`widgets::scrollbar` module which is no longer public. To update your code update any imports to the
+new module locations. E.g.:
+
+```rust
+use ratatui::{widgets::scrollbar::{Scrollbar, Set}};
+// becomes
+use ratatui::{widgets::Scrollbar, symbols::scrollbar::Set} 
+```
+
+### MSRV updated to 1.67 ([#361])
+
+[#361]: https://github.com/ratatui-org/ratatui/issues/361
+
+The MSRV of ratatui is now 1.67 due to an MSRV update in a dependency (`time`).
+
+## [v0.22.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.22.0)
+
+### bitflags updated to 2.3 ([#205])
+
+[#205]: https://github.com/ratatui-org/ratatui/issues/205
+
+The serde representation of bitflags has changed. Any existing serialized types that have Borders or
+Modifiers will need to be re-serialized. This is documented in the [bitflags
+changelog](https://github.com/bitflags/bitflags/blob/main/CHANGELOG.md#200-rc2)..
+
+## [v0.21.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.21.0)
+
+### MSRV is 1.65.0  ([#171])
+
+[#171]: https://github.com/ratatui-org/ratatui/issues/171
+
+The minimum supported rust version is now 1.65.0.
+
+### `Terminal::with_options()` stabilized to allow configuring the viewport ([#114])
+
+[#114]: https://github.com/ratatui-org/ratatui/issues/114
+
+In order to support inline viewports, the unstable method `Terminal::with_options()` was stabilized
+and  `ViewPort` was changed from a struct to an enum.
+
+```rust
+let terminal = Terminal::with_options(backend, TerminalOptions {
+    viewport: Viewport::fixed(area),
+});
+// becomes
+let terminal = Terminal::with_options(backend, TerminalOptions {
+    viewport: Viewport::Fixed(area),
+});
+```
+
+### Code that binds `Into<Text<'a>>` now requires type annotations ([#168])
+
+[#168]: https://github.com/ratatui-org/ratatui/issues/168
+
+A new type `Masked` was introduced that implements `From<Text<'a>>`. This causes any code that did
+previously did not need to use type annotations to fail to compile.  To fix this, annotate or call
+to_string() / to_owned() / as_str() on the value. E.g.:
+
+```rust
+let paragraph = Paragraph::new("".as_ref());
+// becomes
+let paragraph = Paragraph::new("".as_str());
+```
+
+### `Marker::Block` now renders as a block rather than a bar character ([#133])
+
+[#133]: https://github.com/ratatui-org/ratatui/issues/133
+
+Code using the `Block` marker that previously rendered using a half block character (`'▀'``) now
+renders using the full block character (`'█'`). A new marker variant`Bar` is introduced to replace
+the existing code.
+
+```rust
+let canvas = Canvas::default().marker(Marker::Block);
+// becomes
+let canvas = Canvas::default().marker(Marker::Bar);
+```
+
+## [v0.20.0](https://github.com/ratatui-org/ratatui/releases/tag/v0.20.0)
+
+v0.20.0 was the first release of Ratatui - versions prior to this were release as tui-rs. See the
+[Changelog](./CHANGELOG.md) for more details.
+
+### MSRV is update to 1.63.0 ([#80])
+
+[#80]: https://github.com/ratatui-org/ratatui/issues/80
+
+The minimum supported rust version is 1.63.0
+
+### List no longer ignores empty string in items ([#42])
+
+[#42]: https://github.com/ratatui-org/ratatui/issues/42
+
+The following code now renders 3 items instead of 2. Code which relies on the previous behavior will
+need to manually filter empty items prior to display.
+
+```rust
+let items = vec![
+    ListItem::new("line one"),
+    ListItem::new(""),
+    ListItem::new("line four"),
+];
+```

README.md

@@ -74,6 +74,7 @@ more info.
 - [API Documentation] - the full API documentation for the library on docs.rs.
 - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
 - [Contributing] - Please read this if you are interested in contributing to the project.
+- [Breaking Changes] - a list of breaking changes in the library.
 
 ## Quickstart
 
@@ -174,7 +175,7 @@ fn ui(frame: &mut Frame) {
 
 Running this example produces the following output:
 
-![docsrs-hello](https://github.com/ratatui-org/ratatui/assets/381361/9afccfe3-5f33-42e9-9a55-2d143af3b128)
+![docsrs-hello]
 
 ## Layout
 
@@ -187,7 +188,7 @@ section of the [Ratatui Book] for more info.
 use ratatui::{prelude::*, widgets::*};
 
 fn ui(frame: &mut Frame) {
-    let areas = Layout::default()
+    let main_layout = Layout::default()
         .direction(Direction::Vertical)
         .constraints(vec![
             Constraint::Length(1),
@@ -195,27 +196,33 @@ fn ui(frame: &mut Frame) {
             Constraint::Length(1),
         ])
         .split(frame.size());
-    frame.render_widget(Paragraph::new("Title Bar"), areas[0]);
+    frame.render_widget(
-    frame.render_widget(Paragraph::new("Status Bar"), areas[2]);
+        Block::new().borders(Borders::TOP).title("Title Bar"),
+        main_layout[0],
+    );
+    frame.render_widget(
+        Block::new().borders(Borders::TOP).title("Status Bar"),
+        main_layout[2],
+    );
 
-    let areas = Layout::default()
+    let inner_layout = Layout::default()
         .direction(Direction::Horizontal)
         .constraints(vec![Constraint::Percentage(50), Constraint::Percentage(50)])
-        .split(areas[1]);
+        .split(main_layout[1]);
     frame.render_widget(
         Block::default().borders(Borders::ALL).title("Left"),
-        areas[0],
+        inner_layout[0],
     );
     frame.render_widget(
         Block::default().borders(Borders::ALL).title("Right"),
-        areas[1],
+        inner_layout[1],
     );
 }
 ```
 
 Running this example produces the following output:
 
-![docsrs-layout](https://github.com/ratatui-org/ratatui/assets/381361/a18da2a3-1bf4-4939-a5e1-06f3e32bacd1)
+![docsrs-layout]
 
 ## Text and styling
 
@@ -276,7 +283,7 @@ fn ui(frame: &mut Frame) {
 
 Running this example produces the following output:
 
-![docsrs-styling](https://github.com/ratatui-org/ratatui/assets/381361/c16024f7-3d36-4f66-973c-5892b69bca7f)
+![docsrs-styling]
 
 [Ratatui Book]: https://ratatui.rs
 [Installation]: https://ratatui.rs/installation.html
@@ -297,6 +304,10 @@ Running this example produces the following output:
 [API Documentation]: https://docs.rs/ratatui
 [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
 [Contributing]: https:://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
+[Breaking Changes]: https:://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+[docsrs-hello]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
+[docsrs-layout]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
+[docsrs-styling]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
 [`Frame`]: terminal::Frame
 [`render_widget`]: terminal::Frame::render_widget
 [`Widget`]: widgets::Widget

RELEASE.md

@@ -20,6 +20,7 @@ actions](.github/workflows/cd.yml) and triggered by pushing a tag.
 1. Bump versions in the doc comments of [lib.rs](src/lib.rs).
 1. Ensure [CHANGELOG.md](CHANGELOG.md) is updated. [git-cliff](https://github.com/orhun/git-cliff)
    can be used for generating the entries.
+1. Ensure that any breaking changes are documented in [BREAKING-CHANGES.md](./BREAKING-CHANGES.md)
 1. Commit and push the changes.
 1. Create a new tag: `git tag -a v[X.Y.Z]`
 1. Push the tag: `git push --tags`

src/lib.rs

@@ -53,6 +53,7 @@
 //! - [API Documentation] - the full API documentation for the library on docs.rs.
 //! - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
 //! - [Contributing] - Please read this if you are interested in contributing to the project.
+//! - [Breaking Changes] - a list of breaking changes in the library.
 //!
 //! ## Quickstart
 //!
@@ -153,7 +154,7 @@
 //!
 //! Running this example produces the following output:
 //!
-//! ![docsrs-hello](https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true)
+//! ![docsrs-hello]
 //!
 //! ## Layout
 //!
@@ -200,7 +201,7 @@
 //!
 //! Running this example produces the following output:
 //!
-//! ![docsrs-layout](https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true)
+//! ![docsrs-layout]
 //!
 //! ## Text and styling
 //!
@@ -261,7 +262,7 @@
 //!
 //! Running this example produces the following output:
 //!
-//! ![docsrs-styling](https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true)
+//! ![docsrs-styling]
 #![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 #![cfg_attr(
@@ -300,6 +301,10 @@
 //! [API Documentation]: https://docs.rs/ratatui
 //! [Changelog]: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md
 //! [Contributing]: https:://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md
+//! [Breaking Changes]: https:://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md
+//! [docsrs-hello]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-hello.png?raw=true
+//! [docsrs-layout]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-layout.png?raw=true
+//! [docsrs-styling]: https://github.com/ratatui-org/ratatui/blob/c3c3c289b1eb8d562afb1931adb4dc719cd48490/examples/docsrs-styling.png?raw=true
 //! [`Frame`]: terminal::Frame
 //! [`render_widget`]: terminal::Frame::render_widget
 //! [`Widget`]: widgets::Widget