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.

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.

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.

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.

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.

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.