diff --git a/BREAKING-CHANGES.md b/BREAKING-CHANGES.md new file mode 100644 index 000000000..8c0ea6835 --- /dev/null +++ b/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` 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(frame: &mut Frame) { ... } +// 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>` now requires type annotations ([#168]) + +[#168]: https://github.com/ratatui-org/ratatui/issues/168 + +A new type `Masked` was introduced that implements `From>`. 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"), +]; +``` diff --git a/README.md b/README.md index 2e0b0cd53..4a0a32a81 100644 --- a/README.md +++ b/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(Paragraph::new("Status Bar"), areas[2]); + frame.render_widget( + 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 diff --git a/RELEASE.md b/RELEASE.md index 451f1dd85..8411068a8 100644 --- a/RELEASE.md +++ b/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` diff --git a/src/lib.rs b/src/lib.rs index e609287fd..e4dd64e8a 100644 --- a/src/lib.rs +++ b/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