A quick note on breaking changes

[lthoerner]

Hey guys, I just wanted to share some quick thoughts about breaking changes to the crate.

I think that we may be approaching making breaking changes with too much caution; it seems to be the case that the maintainers are loathe to implement them, which is entirely understandable. Breaking changes can make it a pain for users of the crate to keep up with releases if they want access to new features.

However, I believe that one of the important hallmarks of a pre-major-version (you could call it "beta" if applicable) project, is the ability to "move fast and break things." Of course, it should always be considered whether a feature is really necessary, but we've been left with a bit of an underbaked cake from the original tui-rs developers (no offense at all, we've all had projects we didn't truly finish) - and I think that it is often necessary for us to patch existing functionality or add new functionality in ways that are not conducive to backward compatibility.

Overall, my point is that programmers who are not only using a beta crate, but also expecting to frequently update it for new features, should be ready to do revisions to their own code. And, if they do not wish to do so, they can simply not update the crate. Until we release ratatui 1.0.0, I don't think there is any point in being overly devoted to backward compatibility.

I'm looking forward to hearing you guys' thoughts on this. I might be entirely off-base here, but I wanted to bring it up.

[joshka]

+1 I just wrote something related in #122 regarding whether to add new methods to fix the places where we consume widget rather than borrowing it (and which probably applies throughout the entire library for things where we should use borrow or use Cow.

One possible other approach to implementing a new method would to actually break callers by making render_widget and render_stateful_widget actually borrow the widget (and probably area too) instead of having two methods. We're in a spot where it could be reasonable to make a choice to break consumers here if the outcome enables many more scenarios and makes the library more ergonomic - this is probably controversial and I'd defer to those who have more experience than I do on this.

[sophacles]

I'm not particularly opposed to breaking changes, but we should at least note what they are and just how breaking they are.

Something like the addition of an enum variant is far less disruptive than say a major refactor that changes how to construct an app. Even if the users are expecting breaking changes it's nice to at least tell them what we broke so they don't have to stare at diffs to track it down.

I also think major changes should involve some discussion and feedback time from users - a couple reasons for this:

1. If major changes are going to happen, it's nice to find out if the users actually want that, or if they have other related changes that can be bundled into the same release to reduce downstream toil.

2. Major changes should be planned - it's easy to make big changes that seem convenient or useful but paint the library into a corner or reduce its broad applicability.

This library existed in stasis for a long time. Independent of some semantic versioning argument, lots of software exists for decades in a relatively stable state with a <1 version number. When it suddenly starts dropping breaking changes on a regular basis, it's annoying (at least, sometimes downright infuriating). I think it's worth being deliberate (not pausing breaking changes, just being deliberate) for a while to respect our users that might be surprised by the new revival. I know they have to make a conscious choice to switch from tui-rs to ratatui, but that change does not imply a sudden change in development cycles/patterns.

[lthoerner]

In some cases it will be close to impossible to maintain backwards compatibility without making the codebase a bit of a mess (see our discussion on #175 about maintaining compatibility with unnamed fields). I agree with your last point, but when it needs to happen, I think it's totally fine as long as it's well-documented for the users (I think that being very reluctant to make changes is somewhat unnecessary).

At the end of the day, if tui-rs had a great existing API I wouldn't be so gung-ho to revamp/refactor it in major ways but it has quite a few problems that can only truly be fixed by breaking changes. What is the purpose of ratatui if not to fix the pain points created by tui-rs?

[sayanarijit]

see our discussion on #175 about maintaining compatibility with unnamed fields

I think unnamed fields shouldn't be public. But if it's already public, it should be left as it is. We can keep both: compatibility and a clean codebase by moving things here and there a bit.

What is the purpose of ratatui if not to fix the pain points created by tui-rs?

As the readme says, we want to continue development by building upon the foundation already laid by the original author, not a complete rewrite/refactor of the tui crate. Still I believe there's potential to go a long way even if we keep breaking changes to a minimum.

[lthoerner]

If we were talking about this after a 1.0 release I would tend to agree with you, but we're not, so I think we should be fixing bad design rather than accommodating it. You can only make so many additive changes without modifying the underlying API to an extent.

[sayanarijit]

That actually is a valid point. But majority of the rust crates are <1.0, yet the community try to maintain compatibility as much as possible. So adding frequent and huge breaking changes, using this excuse, without considering the community opinions might not be well received. Also, I guess we're not too far from 1.0 considering the ecosystem we already have. The only thing is we have to wait until all our dependencies are stable enough.

[lthoerner]

My opinion as a user of the crate is that we are a long way from 1.0 - but that is largely up to the maintainers. I understand that a lot of crates don't follow semver closely and I've actually seen this mentioned on r/rust a few times; I think that the relative novelty of Rust as a language tends to push crate developers toward "forever beta" releases. My thought on that would be that we should be doing it right rather than just following the crowd, but I can see arguments either way being compelling enough.

[Byron]

I really appreciate all the energy and excitement the new maintainers are showing here and believe this should lead to the best possible TUI library possible even if it entails breaking changes. Personally, I am happy with how my software looks like (dua-cli, prodash), but also had to workaround a few issues tui-react crate. Hopefully, thanks to your work, that can go away one day.

That said, I'd be happy to wait until 1.0 even and then upgrade everything at once, which should be straightforward as there is excellent documentation that lets me search for old names and trace forward to how its supposed to be used now. Doing this in little steps might be easier, but I'd only do so if forced (for instance, by CVEs or other issues due to outdated dependencies). Right now, I'd love to just keep things working for as long as possible.

That said, there might be an opportunity here as well, as you could validate breaking changes against the top-list of your users. At the very least that would give them the upgrade to the next version for free, and at best you get to create even better/more convenient APIs.

All the best!

[joshka]

P.s. @Byron's crates are the top of the tui reverse dependencies list by about 10x compared to the next closest (tui-logger, tokio-console, gitui)

[lthoerner]

I think this is the way to go - maintaining the drop-in version for the time being with essential patches, while developing 1.0.0 without too much reservation for making API updates, and thoroughly documenting the API changes so users can upgrade when the time comes to make a major version release. I think that it just isn't feasible to make only additive changes to a product that was abandoned halfway through.

Happy to hear from the developers using ratatui in their own projects. Thanks for the feedback!

[mindoodoo]

maintaining the drop-in version for the time being with essential patches, while developing 1.0.0 without too much reservation for making API updates

I like this idea, however I think if we were to take this approach we would need to be clear with what we really want to do for 1.0.0, instead of just feeling more free to introduce breaking changes. I don't believe we should develop two versions side by side forever which is why we should know precisely what we're striving for if we ever start work on 1.0.0 while maintaining the available version.

But all in all, if we ever reach a point where we have a clear idea of what changes we would like to implement for 1.0.0, I agree with @Eyesonjune18 in saying this would be a great way to do it.

[lthoerner]

Well yes, but also keep in mind that requirements will change over time. We won't necessarily know all of our end goals before starting development. But I'm definitely open to hearing roadmap ideas.

[lthoerner]

One thing I thought to mention is - even entire programming languages do frequent breaking releases. How many apps use Java, for instance? And of those, how many are still on Java 8 because it works for their needs? And then you have languages like C++ who sacrifice correctness and ease of use for backward compatibility, which IMO is not something we should strive for. Of course, not all languages and software projects should do release cycles like Java, but it's not like the idea of having to modify your application to use new features is a foreign one to the development world. I don't think it should require weeks-long conversations/debates every time we need to rename a struct field. To reiterate past comments, I'm confused why we're talking about this crate like it's some sort of legacy software when it hasn't even had a major version release yet.

[lthoerner]

I don't think that the second option requires abandoning the current userbase. I think you may be thinking of this a bit too drastically. The top user of the crate has weighed in above, and it did not seem that their statement fell anywhere near saying "I will stop using Ratatui if any major changes are made."

Regarding your third option, my point all along was that we shouldn't have to take everything incredibly slow and steady. As long as we're not being outright hostile to the thirty-some people using our crate, and are able to effectively communicate changes as they happen, I see it as a waste of time to sit and wait for feedback on every single change. The issues I have with this approach can be summed up as such:

• The original design is not all that great in a lot of places. Additive-only changes aren't feasible if we want to make any major improvements.
• The userbase is neither large nor active enough for us to get quick and meaningful feedback on most features, especially minor ones. Requiring user review for even minor changes seems like more of a burden than a boon to users.

See my comments above for a more complete idea of the approach I think we should take.

[sayanarijit]

So yes, in your example, we're the c++ community, trying to maintain it, due to either - rust hasn't been released yet, or we don't think rust it worth migrating to, or it's not possible to migrate, or any other reason you'd think of. It doesn't really matter if it's c++ v1 or v0.1.

Edit: sorry for the redundant comment.

[sayanarijit]

The userbase is neither large nor active enough for us to get quick and meaningful feedback on most features, especially minor ones. Requiring user review for even minor changes seems like more of a burden than a boon to users.

Here I don't agree. There's no other alternative that comes close to tui-rs ecosystem. Reg activeness, It depends of how you measure it. Different ecosystems have different level of activeness. We're definitely not as active as react or any other js framework. But compared to tui-rs alternatives, I think we're the most active community.

Update: also we don't require user review for minor changes. We just straight away merge them as long as it's not breaking.

[lthoerner]

Most active ≠ active. I wouldn't call this library particularly popular even though you are correct in saying it's probably the most popular TUI library outside of the original tui-rs. Just because we have a proportionally large userbase does not mean we have enough people to get meaningful feedback on every change, or even just most of them.

[sayanarijit]

We won't ask user review from all or most users, but as @joshka mentioned, we should atleast get review from users who are at the top of the reverse dependency list. And I'd add we should definitely get review from third party extensions authors, if we break their extensions. Large or small, popular or unpopular, fact is that we have users and a community, and we want to keep them.

[Byron]

I find it really hard to find the right place to chime in, and guess a new top-level reply is the best option.

As mentioned earlier, even though having no work with ratatui thanks to stability is valuable, at this point at least to me it's as valuable to have regular updates and active maintainers. I do remember how slow interactions with tui were back in the days, and I definitely prefer the fast pace here.

Making ratatui the best possible TUI crate is also a valuable goal to me, as it would enable better TUIs for Rust software of all kinds. This will mean breaking changes and to me that's perfectly fine if…

• they are not done in a vacuum but on actual users of the tui/ratatui crates
• they won't be fully or partially undone by later updates (or at least that's the rare event, mistakes can happen)

The first point, not making breaking changes in a vacuum, deserves some more explanation as it to my mind gets to leverage the relatively small user-base of the tui crates: You can know your users and they probably cover 95% of the user-cases already. If you had a selection of crates against which you test all changes, I think the chances for these to be good are much higher with the side-effect that upgrading your key users is only a PR away. With such a workflow, users would even be able to provide early feedback on draft PRs if that's what they desire.

Of course, this also means extra effort in understanding the code-bases of these tui users, while trying to extract their problems and workarounds to get a first set of possible improvements to make. As a practical example, to be able to do dua-cli, I felt the need for creating tui-react which fixes some issues I had with the tui API. What can be done to not need that utility crate anymore? Are there better solutions to the problem tui-react is solving? What's the effect of such changes to other key-users? What's the minimal viable change to remove that wart?

To me, the outlook of more active and practice-oriented development is very exciting, as I believe it can lead to Rust finally getting the TUI crate it deserves (the best, of course 😁).

Probably there are parts of the community that happily stay with tui as it works for them, and who didn't make it onto the list of privileged crates against which all changes are validated. To me, that's fine, as nothing would prevent you from submitting a PR if you think they should make the switch. Maybe some of them will make the switch by themselves because it's obvious that ratatui is for their benefit, and because there is a well-maintained *migration document` to help them along.

I think a lot of what I am saying here is based on my experience with gitoxide, which wants to eventually replace git2 (among other things), and making upgrades for early-adopters is what I do regularly, along with the occasional 'oxidization' where I create a PR to switch to gitoxide. Doing this is so valuable as I get to improve the API along the way to be as good or often times better. I truly think it works.

[joshka]

The Spans -> Lines rename caused the following issues downstream:

• error[E0308]: mismatched types kamiyaa/joshuto#321
• failed to install the latest version kamiyaa/joshuto#318

These issues were brought to the attention of the owner by users attempting to install the tool using cargo install. It highlights that the problem we cause by breaking compatibility is not just one where we break our direct downstream developers using ratatui in their crates, but that we also break the users (or potential users) of the tools built with ratatui.

I know that apps should include a Cargo.lock and should be installed using the --locked flag to avoid issues like this, but we can avoid these issues too by not breaking compatibility (at least as a general rule).

[orhun]

I also have a similar issue in my project: orhun/systeroid#89 (see failed pipelines)

[sayanarijit]

Cargo does update minor releases if --locked is not used. For us, 0.20 - 0.21 may be a major release, but not for cargo I guess.

[joshka]

I also have a similar issue in my project: orhun/systeroid#89 (see failed pipelines)

That got bumped to 0.21 as 0.21 was needed by tui-logger.

I can't work out joshuto though. Here's the tree prior to the change

  ~/local/migrate-to-ratatui/joshuto on  @20d51cf1                                                                 took  35s at  06:24:47
❯ cargo tree -i ratatui --all-features
ratatui v0.20.0
├── ansi-to-tui v3.0.0
│   └── joshuto v0.9.4 (/Users/joshka/local/migrate-to-ratatui/joshuto)
└── joshuto v0.9.4 (/Users/joshka/local/migrate-to-ratatui/joshuto)

I wonder if there's some different dependency versioning for install compared to build?

[jw013]

This appears to be a case of multiple conflicting versions. joshuto itself depended on ratutui 0.20 but its ansi-to-tui dependency declares a "0.*" dependency on ratatui which is how 0.21 wound up in the build. I think "0.*" dependencies are probably a bad idea, perhaps an issue should be filed with ansi-to-tui.

[joshka]

uttarayan21/ansi-to-tui#31

[haydenflinner]

I'm just dropping by to comment that the only reason I'm here, using this crate, is because cursive is hesitant to break things by introducing lifetimes, which makes my life as a user harder than necessary. My thought is that ratatui will likely move more quickly in whatever direction the community thinks is ideal.