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.

[michaelkirk]

Just hit another surprise related to i_overlay not following semver.

apache/sedona-db#566 is failing to build because it cannot resolve i_overlay.

I've looked at it a bit, and I think this is what's happening:

In our previous discussion, you said i_overlay didn't intend to follow semantic versioning and will occasionally break (in the semver sense) API methods in "minor" releases.

This policy caused a minor i_overlay release to break compilation for our users.

To avoid repeating that, geo now pins conservatively to specific minor i_overlay versions (i_overlay = { version = "4.5.1, < 4.6.0" }).

As far as I know, this approach has worked OK.

Now there is a crate geo-index which wants to support multiple versions of the geo crate. This should be fine. We do similar things in geo-types which adds support for new versions of rstar while maintaing support for the older ones.

But this only works because rstar follows semver. The issue is that cargo assumes crates follow semver. In order to decrease build times, cargo unifies dependencies by assuming they use semver.

So, going back to the issue in question, they want to depend on multiple versions of geo, which in turn depend on different versions of i_overlay:

However:

• geo: 0.31.0 - depends on i_overlay: version = "4.0.0, < 4.1.0"
• geo 0.33.0 - depends on i_overlay: version = "4.5.1, < 4.6.0"

From cargo docs:

If two compatible versions cannot be unified because of conflicting version requirements, Cargo will error.

So cargo wants to unify those two versions of i_overlay, since they are versioned as if they are semver compatible, but geo explicitly doesn't allow it, so cargo explodes.

If instead, you were to start following cargo's convention of versioning, we could safely relax geo's i_overlay dependencies like:

• geo: 0.31.0 - depends on i_overlay: version = "4.0.0"
• geo 0.33.0 - depends on i_overlay: version = "4.5.1"

And cargo would happily unify a crate depending on both to 4.5.1. Or, if you actually broke something (in the semver sense), this would also be fine:

• geo: 0.31.0 - depends on i_overlay: version = "4.0.0"
• geo 0.33.0 - depends on i_overlay: version = "5.0.0"

Because cargo assumes "4.0.0" and "5.0.0" are semver incompatible, it won't try to unify them, and it would mean multiple versions of i_overlay get built, but that's the desired outcome in the case of incompatible versions, rather than a cargo error.

[NailxSharipov]

Yes, I have come around on this. I understand the importance of semver in the Rust ecosystem much better now, and my earlier position was mostly due to inexperience on my side.

There are public API differences between 4.1 and 4.5.1 not just expand, so backward compatibility not exact. For example, OverlayOptions is changed, ogc flag was added.

I am planning to publish 5.0.0 in the next couple of days and this will be first semver release. I will also integrate cargo-semver-checks into the release process.

[michaelkirk]

I'm very glad to hear that. Thank you @NailxSharipov!