Examples use unreleased code incompatible with 0.25.0

[joshka]

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, sometime that code will be incompatible with the current release. The examples then don't always compile with the current release.

Workarounds

There are a few ways to work around this problem:

• view the version of the examples aligns with the version of Ratatui that you're using. E.g. https://github.com/ratatui-org/ratatui/tree/v0.25.0/examples
• compile the examples with a local version of the source code rather than the released version
• update to the latest -alpha release which is generally released weekly on Saturdays. E.g. https://crates.io/crates/ratatui/0.26.0-alpha.1
• To work out whether the code is a 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 ...

[joshka]

• docs(examples): add warning about examples matching the main branch #778 puts a message at the top of the examples README file.

@Valentin271 suggested:

What about linking the example directory of the latest release?

[joshka]

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

Supporting multiple releases rather than just the most recent is much more effort than only supporting the latest release. I think in general we should only support the most recent release.

The main branch will always have code in it that had changed since the last release, leading to this being out of sync with the released version. This is the nature of every open source project that does development in public.

If a user wants examples that work with a specific release, they can load the tag that is associated with the release. This is available on the main page of every repo:

[kdheepak]

I think in addition to the examples here in the repo, we could automate showing the examples on the website:

• The website could show the examples for the latest tag
• We could render the latest versions of the repo but permanently store all past versions in a gh-pages branch, like this for e.g.:

Then we can set up https://ratatui.rs/ can redirect to https://ratatui.rs/latest which could be a symlink of the folder with the latest tag. We can also add a dropdown for users to see the old website.

I think this second point is a nice to have feature but not high priority.

[joshka]

It seems like a lot of work to set this up (and then to maintain / make it work with the automatic previews / etc.), when the workaround is:

• locally: git checkout v0.25.0; bat examples/tabs.rs
• on GitHub "select the relevant tag from the drop down"

I'd lean towards not making that tradeoff.

[joshka]

Perhaps a better approach might be to explicitly tag any code that does not compile in the latest version with a comment? Or perhaps there's an attribute that does a version check (which will allow us to fail a build if we don't remove after release).

I'm imagining something like:

#[new-in("0.26.0", url="https:://github.com/...")]
someCode

Edit: I think this might be overkill for the problem. Linking direct to the readme in #844 seems like a better idea.

[kdheepak]

Currently, my understand is that users open GitHub, click on the examples folder, and open whatever sounds interesting to them. The README on GitHub is below our long list of example files. If they are then interested in running it, they create a new project, add ratatui, copy paste the example and it breaks.

This is largely a GitHub UX problem imo. If for example GitHub allowed us to make a tag the default landing page, we wouldn’t run into this issue. Or if we changed our workflow to develop and main was always just the latest releases, this would solve our problem. I suspect just seeing a develop branch when they land on GitHub will hint to users what is happening when their code fails to compile.

I have a simpler idea that we can try. Currently we have:

• ./examples/tables.rs

I propose we have

• ./examples/nightly/tables.rs
• ./examples/README.md

This way clicking on the examples folder will result in the README being prominently displayed.

i.e. we don’t have any files except the readme at the folder level of the examples.

The README can even be the same readme but click to the latest tagged release.

[kdheepak]

Another alternative is to make all single file examples also work with cargo script. A comment at the top of each example file should also do the trick.

[joshka]

I really don't like the dev branch approach, mainly because it's a convention that leads to "I fixed this bug on main" / "It's already fixed on dev, sorry" and also "here's my PR" / "can you please rebase it on dev"

The comment at the top of each example is something I want to do.

I'm not how cargo script helps this problem. Copy paste would still be an issue for users and I think it would make using the changes from main in the examples. It's also an extra complexity added in an area we should keep simple.

This is largely a GitHub UX problem

No disagreement. Would be nice to be able to say "hide the files by default" in any directory.

I propose we have...

This leads to the history of the examples being fragmented somewhat, and extra work managing copying the updated changes over the old changes every time we release. I think this is a problem.

A start to reducing the scroll needed before the README is to move the tape files to another directory.
Another approach would be to move all the examples into a single example with a command line parameter to choose which example to display. The benefit of this is there ends up just being 1 main example instead of a bunch. We'd need to harmonize the app and keyboard handling a bit better (but that's probably a good thing). If we did this, I'd want to keep the application flow simple - no components, no event mapping, no commands, no actions, no async, etc. Linear, obvious code that makes it easy to understand how the app ends up rendering each example is key here.

[Valentin271]

What about having a latest branch? This is similar to kd's idea but we keep developing on main.
We could then really easily link to this branch instead of vx.x.x? At each release we'd just have to rebase the branch and voilà, links to examples are updated.

We could also make it the default displayed branch on github, but that leads to what joshka said about people fixing already fixed bugs.

[joshka]

That could work, but it could also bring confusion. I'd still prefer main to be the default branch shown it's what people will submit PRs against etc, and it's what you want to show as being active.

I'm tempted to say move the examples out of the repo, but a big benefit to having them in the repo is that we see the sorts of pain that our users would have to undertake any time we have a breaking change. If it's difficult to do on our own small apps, then that pain is magnified. So keeping the examples in the repo helps us empathize with our users and avoid doing dumb things.

[Valentin271]

I'd still prefer main to be the default branch shown it's what people will submit PRs against

I'm fine with that, was just stating any possibility. There's still the (big) benefit of linking to the same branch that gets updated.

I'd like to keep the examples in the repo too, for what you said but also because this is the standard Rust project layout. I like that on pretty much any Rust project I know where the examples are and I can find them (and even run them) in seconds.

[kdheepak]

This leads to the history of the examples being fragmented somewhat, and extra work managing copying the updated changes over the old changes every time we release. I think this is a problem.

I'm suggesting just moving all examples we have one level down, so the examples folder has a README.md and just one folder. And keep everything else about our workflow the same. I called the folder nightly but very open to alternate names.

I really don't like the dev branch approach, mainly because it's a convention that leads to "I fixed this bug on main" / "It's already fixed on dev, sorry" and also "here's my PR" / "can you please rebase it on dev"

I don't like different branches as well just because when you make a PR on github it makes it to the default branch of the repo. The only solution that kind of works here is making develop the default branch and merge / squash to main only when making a release. Because what I've found is that when see the default branch is develop, then know they have to switch to main when they want to look at examples.

to be clear, I'm certainly not suggesting we use a develop branch. If nothing else, I like the simplicity of just one branch main and the git history of it, and I'm up to try a number of different approaches before I could even consider a develop branch approach. My point is simply that this is a UX problem, and we can try to improve the flow in a number of different ways.

[joshka]

How about we see whether the examples readme fix helps for a little while and go from there. I'm guessing that this should fix most of the problem, but we can also prioritize which option to try next if it doesn't.

[jaskij]

An option which, while it won't eliminate the pain completely, would probably alleviate it. docs.rs and your website should link to the correct version, not to the main branch.

For mdbook, there is something called preprocessors, which allows you to essentially run a pre-build script. It would then be a matter of obtaining the current tag/version and doing a mass search-and-replace, which I do not know enough about docs.rs to know how to get the version.

I'm not sure about Astro, but since it's probably ran in your own CI, something similar should be doable, probably just with git describe and sed.

This won't fix the issue completely, but the people who click the link on docs.rs or on your website at least will be directed to the correct place. This is something that can be done quickly.

[joshka]

To be clear - most of the time I want to link to the most current example code, mainly because we move fairly rapidly with that code and update it at a higher cadence than the release schedule (every 6 weeks or so). Example code generally multiplies out as people copy bad practices or deprecated methods etc, so using older versions of the examples should not be the norm.

We do need to get into a habit of releasing minor releases in between that 6 weeks, which would generally fix some of this, but in the last two releases we've made some breaking changes fairly soon after the release, so a new release would have to be a major one.

[jaskij]

To be clear - most of the time I want to link to the most current example code

The solution I proposed would link them to the one which was released together with the documentation. So, if they're reading the most recent documentation, they'll be linked to the most recently released version.

The question is, I think, whether a quick fix which helps now, and can be reverted later, is something you're willing to apply.

We do need to get into a habit of releasing minor releases in between that 6 weeks

While I'm an outsider, I'm not sure point releases would be healthy at this point in the project's life. You're moving fast and breaking things a lot. Simply own it and tell people. Put a giant warning at the front of your page "Ratatui is moving fast and breaking things".

Thinking further, yes, I think that's it - it's a mismatch between people's expectation and the actual lifetime stage of Ratatui. You're still early, iterating on the API design, moving fast and breaking things. People treat the project like it was a stable library.

[joshka]

The solution I proposed would link them to the one which was released together with the documentation.

I prefer users to see the latest available version of the code. Not the version released with the release.

You're moving fast and breaking things a lot.

Kinda - I've done quite a few tui to ratatui migrations in various projects to check out how much breakage there really is. For the most part it's Spans -> Line, Frame<B> -> Frame, and adding a check for KeyKind::Pressed on the crossterm event handler.

I'd say it's more move fast and break things with caution.