Note: this is a pinned post for visibility

Summary

We write code on the main branch, and update the examples to align with that code. This will become a future release (usually around 6-8 weeks between releases). When we implement new code or change behavior, sometimes that code will be incompatible with the current release. The examples then don't always compile with the current release.

In the upcoming 0.30 release, we're also splitting the Ratatui crates as part of #1388 in order to make it easier for downstream crates to rely on more stable parts of Ratatui and make it easier to upgrade applications between versions. As part of this effort we're also moving around the locations of the example files a fair bit, so there may be broken links for some time.

Workarounds

There are a few ways to work around this problem:

• We generally copy the latest release examples to the website at https://ratatui.rs/examples/
• We also generally make sure a branch named latest points at the latest release, so the examples that match whatever we released last are available in https://github.com/ratatui/ratatui/tree/latest/examples
• We tag each release version, so you can find the examples which compile against the exact version of Ratatui that you're using. E.g. https://github.com/ratatui/ratatui/tree/v0.25.0/examples
• The version of the examples in main, generally compile with the code that is main, you can clone from this repo and use the source code version of ratatui rather than the released version to run the examples in main
• Sometimes, we make changes that break the examples to main. To work out whether the code is an expected breaking change, see the BREAKING-CHANGES doc.

Details

In #773 we discovered that changing the examples in the main branch can be confusing when the code in the example doesn't match the latest released docs / libraries.

@Libroru wrote:

I updated the tabs.rs example to use the new syntax for tabs.
Other examples might need to be changed as well.

@kdheepak wrote:

This PR changes it from the new to the old syntax. Can you clarify where you read about this? If anything has to be changed to the new syntax, it is probably our documentation on the website.

@joshka wrote:

Ah, that would make sense. I didn't think about how this sort of thing would affect users when updating the examples. Oops.

@libroru wrote:

That's how I got it working in my personal projects with version 0.25.0. But yeah in addition to that the documentation also shows the old syntax. I figured that that would be the new syntax since it worked on a local installation of 0.25.0.

@Valentin271 wrote:

Links to github should also point to the released tag, not main. Otherwise the links always points to unreleased items.

Probably same for the website?

Edit:
That would mean rigth now the doc should point to 0.26 ... Or the next alpha version. That's kind of hard to maintain ...