semver hazards: use ^ instead of >=

[benjajaja]

Closes #35 - more details in that issue.

In general this should make ratatui-image be more flexible to pick the same version as dependant or sibling dependencies.

[Nemo157]

^0 is almost certainly not correct, 0.24.0 to 0.25.0 is a breaking change under Cargo semver requirements. Generally it's best to just specify full version numbers (setting the known compatible minimum patch version), relying on the default interpretation of ^.

[Nemo157]

more flexible to pick the same version as dependant or sibling dependencies.

This is just not something that cargo supports in general. If you want the same version as dependents you need to reëxport the crate and have dependents use that reëxport instead of depending on the crate directly. The only way to use the same version between siblings (given dependencies that allow for multiple semver incompatible version ranges) is for each application developer to manually downgrade/upgrade selected versions till they're all the same e.g. cargo update -p image:0.25.2 --precise 0.24.9.

For maintained crates it's far easier to just push the ecosystem forward by updating to new breaking versions of public dependencies ASAP, if everyone is running the latest version then everything works together cleanly. Trying to maintain multiple-breaking-version compatibility can be wasted effort.

[benjajaja]

@Nemo157 could you check this now? I changed to ^ for everything.

I tested this with iamb which you're familiar with, and this only required minor adjustments due having a mismatched version of image (presumably from the existing Cargo.lock there).

[benjajaja]

@joshka sorry to ping you like this, but I think you know a lot about how projects use / should use ratatui, could you perhaps check in on this?

[joshka]

No problem. Happy to look.

https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#caret-requirements

Leaving off the caret is a simplified equivalent syntax to using caret requirements. While caret requirements are the default, it is recommended to use the simplified syntax when possible.

For working this out, I'd start with listing out the types that appear in your public API. Anything not in your public API will not cause problems unless there's internal state of that library that you expect to work (e.g. Crossterm stores the state to exit raw mode in a static variable). So for the things not in your public API choose the version that earliest version that contains the code that matters to your usage in the latest minor version. The version that you pick here will impact any dependents that use the same semver compatible version as your crate, but that's generally the dependent's problem not yours, so I'd generally just use and test with the the latest and let dependabot do its thing to keep that up to date.

For things in your public API, you really can only depend on a single semver version. Building your library will pick the highest matching semver compatible version that you specify even if there are other crates that are being built which specify lower versions. This is what makes the >= problematic. >= 0.25 really means 0.28 currently (and will allow apps to use 0.28.0 and 0.28.1 because of semver.

Ratatui is in the public API of most widget crates because the widget trait needs to be the same semver compatible version.

If you need to make this crate work with the earlier versions, then it's common to use feature flags to bring in specific versions. E.g. you might have a ratatui-26 flag that includes ratatui 0.26 and so on. This is probably not worth it though.

Instead I'd suggest for now just support the latest versions of Ratatui 0.28.1 and crossterm 0.28.1, termion 4.0, and setting up dependabot to create PRs when the crates update. If you bump your major version whenever bumping ratatui versions then your users don't get automatically updated.

In the next couple of months (ratatui 0.30 timeline), we're aiming to modularize ratatui so that you can instead rely on a slower changing ratatui-core crate, which won't get bumped anytime there's semver breaking changes in widgets, only in the core types. This should mainly solve the problem of tracking ratatui versions in lower effort way.

[benjajaja]

Thanks a lot @joshka, I'm gonna just update to ratatui ^0.28.1 with #41, and there I could also simply remove crossterm, termion, and termwiz and use ratatui's. Awesome!