search

bojand / infer

Small crate to infer file and MIME type by checking the magic number signature
MIT License
299 stars 28 forks source link

What were the semver breaking changes `0.13` -> `0.14`? #90

Closed alexheretic closed 1 year ago

alexheretic commented 1 year ago

Hello, thanks for your work on this crate. I noticed you published a new version and came to see what the break was and how/if I needed to adapt to that change downstream.

I can't see any breaking changes in https://github.com/bojand/infer/releases/tag/v0.14.0 though. How come this was published as a breaking semver bump?

If a change has no breaking changes it can make life a bit easier downstream (ie for me) by publishing as a non-breaking semver bump.

alexheretic commented 1 year ago

Ah I assume you just don't follow semver. That makes it harder to continuing using this crate. But if you never intended to follow semver sorry for the noise.

bojand commented 1 year ago

Hello, my intent is to follow semver, however strictly speaking, when major version is zero (ie 0.y.z), technically anything may change at any time. That being said I am careful about changes in this crate. There were no breaking changes as you stated. Normally I use patch version update for only minor superficial fixes or changes. When something new gets added (like zstd skippable frames in 0.14) I do increment the minor version to signify "something new". Should there be API or breaking changes it will be clearly noted in the release notes. I do have plans for some changes in the future when I get some more time that may require API changes over time, but even those I will try to be iterative and careful with. Sorry for the confusion. Hope this helps.

alexheretic commented 1 year ago

Thanks for the response, it's great you'd like to follow semver.

however strictly speaking, when major version is zero (ie 0.y.z), technically anything may change at any time. That being said I am careful about changes in this crate. There were no breaking changes as you stated.

This interpretation is not correct. I will try to explain in detail. Though I accept the semver 2 spec doesn't make it clear, in rust semver-with-leading-zeros is very well understood by cargo and the crates ecosystem as a whole.

See https://doc.rust-lang.org/cargo/reference/semver.html#change-categories

Initial development releases starting with “0.y.z” can treat changes in “y” as a major release, and “z” as a minor release. “0.0.z” releases are always major changes. This is because Cargo uses the convention that only changes in the left-most non-zero component are considered incompatible.

A breaking change causes churn downstream because cargo update cannot update to it without manual intervention. This can be non-trivial if you consider deep dependencies trees. But it makes sense as the change has been marked as a breaking one.

Non-breaking changes to "0.y.z" crates must increment "z" to denote it is non-breaking. This is the only way cargo update can tell this update is non-breaking. Such updates work throughout the whole dependency tree with a cargo update call and so are easy to maintain downstream.

An extreme example would be libc which would cause a ton of churn were it ever to move off 0.2.x. (Though there is the semver trick, but I won't go into that).

If you want to distinguish between "minor" & "patch" changes in a way that works with cargo you'll need to release a 1.0.0 version and work from there.