Change examples folder structure

[kdheepak]

Problem

It's easy for users that copy paste code from the main branch into their code base that contains a stable release. I know I've done this accidentally even after knowing that the main branch contains code for the next release.

Currently this is the folder structure for the examples:

$ tree examples

├── README.md
├── barchart.rs
├── block.rs
├── calendar.rs
├── canvas.rs
├── chart.rs
├── colors.rs
├── colors_rgb.rs
├── constraint-explorer.rs
├── constraints.rs
├── custom_widget.rs
└── example1.rs

I propose it should be changed to this:

$ tree examples

├── README.md
└── v0.23
    └── README.md -> has one line that links to https://github.com/ratatui-org/ratatui/tree/v0.23.0/examples
└── v0.24
    └── README.md -> has one line that links to https://github.com/ratatui-org/ratatui/tree/v0.24.0/examples
└── v0.25
    └── README.md -> has one line that links to https://github.com/ratatui-org/ratatui/tree/v0.25.0/examples
└── v0.26
    └── README.md -> has one line that links to https://github.com/ratatui-org/ratatui/tree/v0.26.0/examples
└── dev
    ├── README.md
    ├── barchart.rs
    ├── block.rs
    ├── calendar.rs
    ├── canvas.rs
    ├── chart.rs
    ├── colors.rs
    ├── colors_rgb.rs
    ├── constraint-explorer.rs
    ├── constraints.rs
    ├── custom_widget.rs
    └── example1.rs

This way a user has to "opt-in" to choosing the version of the examples after clicking the ./examples folder.

On GitHub, it'd look like this:

It's still low maintenance burden for us and would greatly increase the chances of falling into the pit of success.

[joshka]

Seems like a bit more organization than really needed. An alternate would be to create a branch named latest that always points to the most recent release and point to as a default when talking about examples. E.g. https://github.com/bevyengine/bevy/tree/latest/examples

[kdheepak]

I think the problem is when people don't read the text and click on the github presented examples folder, look at the code, copy paste it, possibly modify it for their application, and run it to have compile errors. In this workflow, additional text in README or comments will not really help imo.

We can either:

1. just not solve for this problem, expect that users read the README and comments, and advise people when they ask for help
2. change the default branch
3. change the examples folder structure to make it self-evident

fwiw, I saw bevy using the latest in their README after reading through their main branch code myself. If I had tried to run their examples, I'd have possibly run into the same issue. I ran into this issue with tauri myself too.

I don't think there's a good way to solve for this unfortunately. The solution in this issue is the lowest effort for us to help with this imo.

[joshka]

1. I think it's reasonable to just respond to these with a FAQ url - I don't think this problem is wide spread enough to over-engineer a solution like this that costs to manually maintain on each release.
2. This is not changing the default branch - just making sure that there is an always up to date location to point to that has the code they need
3. if they're already in /examples/dev, and they haven't read the comment at the top of the file, and they haven't read the comment of the top of the readme, and their struggling to build, I don't think having extra folders would help in any way.

fwiw, I saw bevy using the latest in their README after reading through their main branch code myself. If I had tried to run their examples, I'd have possibly run into the same issue. I ran into this issue with tauri myself too.

I got there via the quick start next steps page which links to the right place. With my two proposal to put more info on the examples in the website, and make that the main place where they're seen, as well as to link from the website code blocks directly to the code, I think that hits most of the points necessary to make this work.

[kdheepak]

if they're already in /examples/dev

in my proposal, we'd never link to dev anywhere and the only way they'd get to examples/dev is by clicking through examples and seeing the other folders.

I also agree that this problem isn't wide spread, and once a user learns that this is an issue they hopefully will remember it from being burnt. imo I think this will decrease the problem happening more but I'll close this issue if we think this is not worth it.