Reconsider C-STABLE guideline

[kvark]

Link: https://rust-lang.github.io/api-guidelines/necessities.html#public-dependencies-of-a-stable-crate-are-stable-c-stable

I believe this guideline is inconsistent with reality and based on flawed reasoning.

A crate cannot be stable (>=1.0.0) without all of its public dependencies being stable.

Where does the definition of "stable" come from? Doesn't appear to be from SemVer spec, which just says:

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

It doesn't say that "stable" is ">1.0.0", it only says that "stable" should probably lead to "1.0.0", which is a much weaker statement. I.e. the original spec describes "stable" as an abstract term, and only provides recommendation based on it.

More importantly, the original recommendation is based on the fact that it provides essentially no versioning guarantees before 1.0:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

The difference with Rust ecosystem is drastic and critical: our modified SemVer does provide versioning before 1.0. So pre-1.0 dependencies don't break any more often than post 1.0, technically speaking. Therefore, I argue that the original recommendation about 1.0 doesn't make sense for Rust ecosystem.

To support my argument, I just tried to publish a project depending on pre-1.0 library. And Cargo is happy to do this without any notes or warnings about pre-1.0 dependencies:

    [nix-shell:/x/code/test-stable]$ cargo publish --allow-dirty --dry-run
        Updating crates.io index
    warning: manifest has no description, license, license-file, documentation, homepage or repository.
    See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
       Packaging test-stable v1.1.0 (/x/code/test-stable)
       Verifying test-stable v1.1.0 (/x/code/test-stable)
       Compiling mint v0.5.8
       Compiling test-stable v1.1.0 (/x/code/test-stable/target/package/test-stable-1.1.0)
        Finished dev [unoptimized + debuginfo] target(s) in 0.75s
       Uploading test-stable v1.1.0 (/x/code/test-stable)
    warning: aborting upload due to dry run

If "crate cannot be stable" is indeed the guideline you want, then I'd expect cargo to check it and nudge people towards following it. It could simply fail in this case while requiring "--allow-unstable" option to proceed, similar to all other red flags that cargo may see.

[BurntSushi]

I think the idea of the guideline is correct. It probably just needs some rephrasing, although, pinpointing precisely what to say seems a little difficult. The gist of it is that your public dependencies should probably be at least as "stable"/"mature"/"rate of breaking changes" as your own crate. Or something to that effect. I think the current wording is just using what folks tend to treat 1.0 as: a point at which a crate's rate of change of breaking API changes "slows."

Notice that I did not reference the semver spec in my response. I don't think it's particularly relevant to this guideline.

[kvark]

I'm not seeing how this guideline would look like then. "Don't depend on less stable libraries"? It's too vague, it's not like any library has a badge on it saying how stable it is.
Overall, as long as we remove "1.0" requirement from this guideline, I believe it would be fixed (and can stay).

[BurntSushi]

These are guidelines. Vagueness is okay IMO.

[minecrawler]

[kvark]

I'm sorry, you appear to completely miss the difference between general SemVer and the one Rust uses, based on this:

0.x, maybe just psychologically, signals that the API is in development and will change and there's no way to tell if I can update to a newer version or if I have to change all my code because of breaking API changes. The x in the case of 0.x does not signal compatibility with all other instances of x. 0.x is good and fine, all software needs to start somewhere, but it should come to a point where compatibility matters, and that's when 1.0 is there to signal the start of compatibility concerns.

In Rust, 0.x.y does signal strong compatibility with other 0.x.z, exactly like 1.y.q is compatible with 1.z.w. So mechanically there is nothing that the major of "1" changes. Compatibility matters equally both before and after 1.0 in Rust world.

And as for the rest, your trust in a library shouldn't be based on a number. Trust is a hard problem! You can trust based on the author name, commit frequency, organization, etc, at least any of these factors somewhat correlate with the act of doing the work on a library. Version? Not so much. One 1.0 library can have breaking changes every once in a while, while another 0.y library is rock solid.

Finally, you may be avoiding 0.x dependencies. But the reality at large in the ecosystem is that 0.x dependency are totally normal for production code. Grep https://searchfox.org/mozilla-central/source/Cargo.lock for example, which is shipping to hundreds of millions of users.