semantic versioning

[michaelkirk]

When 1.8.0 was released, you removed some public method signatures (e.g. pub fn clip_string_lines(&self, clip_rule: ClipRule) was removed in 3bb968d#diff-4eab68219731ce237078e58c414f631efd8a12cb26868356f053310fd26a427fL17)

Cargo (and everyone else AFAIK) considers this to be a breaking change: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove

In case you weren't aware, "semantic versioning" is almost universally used for crates in the rust ecosystem. So much so that cargo takes advantage of this by optimistically updating forward compatible changes with the default versioning notation.

Because I assumed you were following semantic versioning, this broke things for our users, so in the meantime we've had to fall back to stricter version pinning with i_overlay.

Would you consider adhering to semantic versioning like other rust crate in the future? I think your other rust users will greatly appreciate it.

[NailxSharipov]

I agree, breaking backward compatibility is bad. In my defense, the String Line API in 1.7.0 was introduced in a test phase. Based on feedback, I gained a better understanding of its goals, which prompted me to rename and refine it before fully stabilizing and documenting it in 1.8.0. Another factor was the introduction of the new float-api.

I am still working to find the right balance between adding new features and maintaining backward compatibility.

[michaelkirk]

I'm personally not very concerned about breaking backward compatibility so long as it results in worthwhile improvement. I think you made a good improvement here, and I'm glad to have it.

However, when you do make an API backwards incompatibility, cargo (and all rust users) expect that you will also bump the major version number. According to conventional rust versioning, this change should have produced a 2.0.0 release - that's what concerns me.

I know this can feel strange or overly pedantic if you're coming from a different background. In a lot of ecosystems bumping the "major" number of a software is used to indicate some kind of big branded release - you know, KDE 4.0 or whatever, but for libraries, at least in rust, it's not the case. The version number is only used to indicate what kind of API compatibility you are promising vs. the previous release. A "major" version bump might actually be a very small change.

So it might be strange, but it's useful! And it's definitely what rust users expect. When a crate doesn't follow these rules, its downstream users will continue to find their applications unexpectedly breaking. For example, our downstream users were no longer able to use their programs that relied on the removed methods.

Just in case you aren't already familiar with semantic versioning, you can follow this short rubric for a post 1.0.0 crate and be most of the way to semantic versioning:

version: MAJOR.MINOR.PATCH

1. If you aren't changing anything about the external API, like it's only a bug fix or a perf change or changes to a private method, it's a PATCH bump.
2. If you are adding new APIs but not changing or removing any existing ones, it's a MINOR bump.
3. If you are removing, renaming, changing any public API signature (anything that could break an existing users integration) it's a MAJOR bump.

There's a lot of nuance around the edges, which is why https://doc.rust-lang.org/cargo/reference/semver.html is so long, but the above gets you 90% of the way there.

Ultimately it's your software, and I'm grateful for it, so you can do whatever you want, but know that you will continue to surprise your rust users if you don't follow semver conventions. In the meanwhile, geo will be conservatively pinning this library to not incorporate minor bumps until they've been explicitly approved.

the String Line API in 1.7.0 was introduced in a test phase.

Oh - I didn't realize that! Was that documented somehow that I missed? In the future, a better way might be to have an opt-in feature for unstable features to make it clear where you aren't planning to follow semver.

[NailxSharipov]

Thank you for the detailed explanation. Semantic versioning makes sense in theory, but in practice, I’ve noticed that many projects don’t strictly follow it. While I see the value in the approach, I’ve chosen to align with what seems to be the majority practice for simplicity. To avoid confusion, I’ve added a section about my versioning approach on the main page.