Stream: general

Topic: semver and Cargo feature flags


Jake Goulding (Mar 24 2019 at 14:23, on Zulip):

If I have a function that is only exposed when a Cargo feature is enabled and I change the API of that function, what version number bump would you do?

Jake Goulding (Mar 24 2019 at 14:23, on Zulip):

/poll

Leo Le Bouter (Mar 24 2019 at 16:34, on Zulip):

@Jake Goulding Any API change should be major, should it not? I'd delay the API change in another major release along with lots of other API changes to make it meaningful, but I don't think you should break API compatibility just like that.

DevQps (Mar 25 2019 at 06:39, on Zulip):

It feels a bit painful to increment the major version number for such (smaller) things but I guess major still would be the best. After all: Code could break when upgrading

Luca Barbato (Mar 25 2019 at 12:52, on Zulip):

You could feature-gate the new API with a new feature and bump minor as yet another alternative.

Jake Goulding (Mar 25 2019 at 17:15, on Zulip):

That leads nicely to my actual but related question...

If I have a function that is only exposed when a Cargo feature is enabled, I've specifically stated that that feature flag is for unstable features, and I change the API of that function, what version number bump would you do?

Jake Goulding (Mar 25 2019 at 17:16, on Zulip):

/poll

DevQps (Mar 27 2019 at 06:34, on Zulip):

Mmm, good questions :). My first gut feeling says that a minor increment is appropriate here. Since the main stable API doesn't change.

But at a second thought I believe a different approach might be better. It's just a suggestion but I think I would dp it like this:

Semver states thst you can do whatever you want when at the 0 major version. So in case you feel like your project in general hasn't reached a stable API I would just increment the minor number.

If your project has however reached at least major 1, I think the best way to tackle this is to only publish new stable features of crates. On publishing new (backwards compatible) changes, even if its in a feature, you change the minor, and for non-backwards compatible changes you'd change major (even for features)

When a feature contains unstable functionality and you've already reached a major version, I would allow users to use/test it via a direct repository tag/branch:

project = { git = "https://github.com/userhere/myproj", tag = "1.32.5-beta" }

Or something like this. If you'd specify this in the README people would still have access to unstable features whereas they can rely upon a stable API when using crates.io. When the unstable features are merged they would be published as well!

A bit of a long story, but it's just a though :)

Jake Goulding (Mar 27 2019 at 12:00, on Zulip):

Semver states thst you can do whatever you want when at the 0 major version. So in case you feel like your project in general hasn't reached a stable API I would just increment the minor number.

FWIW, what Cargo implements is a slight twist on this. 0.2 is considered a breaking change to 0.1, and 0.0.2 is a breaking change to 0.0.1. 0.1.0 to 0.1.1 is not expected to be a breaking change.

Nemo157 (Mar 27 2019 at 12:33, on Zulip):

My thoughts are that unstable features don’t contribute to semver at all

Nemo157 (Mar 27 2019 at 12:33, on Zulip):

If you were able to release the changes to the same version that would be fine

Nemo157 (Mar 27 2019 at 12:34, on Zulip):

But since you can’t doing a patch update to be able to release a new version is all that’s needed

Last update: Nov 21 2019 at 23:30UTC