RFC: Rust SemVer 2

[Stargateur]

This RFC propose the Rust's SemVer 2 rules that define version requirement operator that can be used in Cargo to define the version of dependencies that Cargo can choose. The rules use SemVer 2.

Empirical change from Rust SemVer 1:

• Remove ranges >=, >, <=, <
• Remove logical "and" ,
• Add logical "or" ||
• Remove sugar 1.* or 1.0.*
• ~ behavior is now equivalent to ~1.0.*, ~1.* and ~*
• ^ will never consider a pre-release compatible with any other pre-release or release
• ~0 or 0.0 are not any more valid version requirement

Internal forum thread of the alpha RFC

Rendered

This work can be a base to another RFC about Version Requirement SemVer.

Related to #3263

Plan to split this RFC:

• Make a RFC to add rust_semver field to cargo.
• Make a RFC to depreciate and add new features
• Rework this RFC as if other RFC have been accepted

TODO:

• work on depreciation instead of removal.
• considered use another character instead of reuse ~

[CAD97]

The RFC should probably explicitly provide an alternative for an in-place upgrade (i.e. without the rust-semver = "2" opt-in) and rationale for why the removals are justified, rather than clarifying their behavior. The RFC should also discuss the cost of having two incompatible versions of behavior, and why the benefit of the new behavior outweighs said cost.

Changes which could be applied to current version requirements:

• Clarifying ranges' interaction with pre-releases (given we define ^1.2.3 as >=1.2.3, <2.0.0, the intent is clearly to not include pre-releases in ranges that don't mention them)
• Deprecation of ranges
• Addition of ||, potentially &&, ()
• Deprecation of ,
• Redefinition of versions considered compatible within pre-releases¹
• Redefinition of how requirement operators work when pre-release versions are present¹
• crates-io banning publishing of new crates which do not follow more stringent rules (e.g. banning unbounded >= requirements or deprecated operators)

Changes which require a breaking opt-in:

• Removal (rather than just deprecation) of ranges, ,, ~0, ^0, *
• Redefinition of ~ from "use specified MAJOR.MINOR" to "variable only in the last specified version segment"²

(To reiterate the implicit point in the above: per my understanding of the RFC, the only motivation for making this a breaking change beyond depreciation of easily misusable operators is redefining ~.)

Footnotes

1. Strictly speaking, this is a breaking change. However, due to the near universal agreement that "all pre-releases are compatible", the current behavior, is somewhere between useless and actively harmful, replacing the rules can be done in place. ↩ ↩²

2. FWIW I personally think this is a better definition for ~ ignoring backwards compatibility and matching other ecosystems' behavior, but I also value backwards compatibility more. ↩

[epage]

While this might serve as a north star for other RFCs, I feel like this RFC is too big. There are a lot of different points covered to get to the final picture which can cause

• Long discussion times as we iterate in one area and then shift focus to another
• Hard to follow threads
• Easy to overlook different aspects

I suspect you will have a lot more success in moving this forward if you

• Break these into more incremental RFCs, like RFC: Precise Pre-release Deps #3263
• Start with deprecations rather than removals
• Limit breaking changes and aim for them being towards the end of the process

rust-lang/rust#95290 is an example of this incremental approach where one specific topic is made an RFC even though it isn't usable on its own. Once we decide on that RFC, we can then have another RFC with the requisite APIs so the discussion is focused on a single line of thought for each RFC.

[Stargateur]

I'm not sure incremental change are better for such changes, semver/semver#584 (comment) experience show that even change that should be done are complicated and create security problem. Also, we have no process for depreciation of Rust SemVer 1 in Cargo for now. How do we depreciate behavior of ~ and ^ since we reuse them in Rust SemVer 2 (thus use of ~ with my proposition will emit a warning for Rust SemVer 1 and error for Rust SemVer 2 by default) ? For Rust SemVer 2 rules to work they need to come together not one by one. I can't guarantee that change rule one by one would be nice for Rust. My only claim is that all Rust SemVer 2 rules are nicer for user of Rust. Rust SemVer 1 and 2 have very different approach.

Easy to overlook different aspects

That I disagree, that why I made a "big" RFC, to not overlook the change, to have the final big picture. Thus this focus on the Rules of Rust SemVer 2 not on how Cargo will do, this was out of my skills anyway.

Start with deprecations rather than removals

That not possible for ~ or ^ since we change their behaviour we didn't depreciate them. But we sure can do that for range and ,, 1.0.*, 1.*, 0.0, 0 in Rust SemVer 1.1 and add || in Rust SemVer 1.1. The only case where a user can't replace feature without ~ change is >=1 != ~1 in Rust SemVer 1.

So, first one RFC to depreciate some operator in Rust SemVer 1.1 and add || ? We should be sure we go to a Rust SemVer 2 if we go this road.

And a RFC like use 3263 to clarify ^ for pre-release ? (breaking change)

P.S: Success was not my primary goal, I really take this as a training project that was very interesting, but if you think Cargo should go forward Rust SemVer 2, I will certainly help.

[epage]

P.S: Success was not my primary goal, I really take this as a training project that was very interesting,

FYI I read this as this being purely a learning exercise and that this isn't a serious RFC. Please set expectations like that from beginning, otherwise some of us might put our time and attention to this that we wouldn't otherwise, wasting our time. Without a good clarification on your intentions, I am going to disengage from this and will not have much trust left for engaging in the future efforts to reach out like this. I'm leaving the rest of my response as I wrote it first and figured I might as well not delete it.

---

That I disagree, that why I made a "big" RFC, to not overlook the change, to have the final big picture. Thus this focus on the Rules of Rust SemVer 2 not on how Cargo will do, this was out of my skills anyway.

I was not making a statement on whether you overlooked something but that the discussion of the RFC is likely to overlook something. I've seen this in another RFC where one area got the focus of discussion overshadowing discussions on other areas.

Start with deprecations rather than removals

That not possible for ~ or ^ since we change their behaviour we didn't depreciate them.

That is why this item was focused on removals and not changes of behavior, things like <

if you think Cargo should go forward Rust SemVer 2, I will certainly help.

I am unsure of the value of it; I'm intentionally not reviewing it yet until we have a break down of what should be done so as not to be distracted by the minutia as we resolve more pressing questions.

[Stargateur]

FYI I read this as this being purely a learning exercise and that this isn't a serious RFC. Please set expectations like that from beginning, otherwise some of us might put our time and attention to this that we wouldn't otherwise, wasting our time. Without a good clarification on your intentions, I am going to disengage from this and will not have much trust left for engaging in the future efforts to reach out like this. I'm leaving the rest of my response as I wrote it first and figured I might as well not delete it.

Not what I mean, This is a total serious RFC, I put a lot of work on it, I guaranty it's not just random though and I can guarantee it's much better than current state of Cargo, my point is that since I got so many negative comment before even start the first word of this document I expect, very negative comment, thus I set my expectation over this being accepted very VERY low, I mean it's normal, I literally propose the most breaking change ever in Cargo, I don't expect myself that this be accepted. I just want to expose theses problems to the community. I believe most people don't realize the current problem we have.

I do not desire to fight to fix Rust SemVer 1 problems, and your message here just do that, try to be in my place, I'm a long user of Rust, I have done many big project in Rust but mostly closed source, I have done hundred of stackoverflow contribution for Rust but I don't think much care about that in Rust team governance; For you I come from nowhere even if I use Rust since more than 7 years. And so when dtolnay and you and even djc, you all tell me "don't loose your time make this RFC", dtolnay even say the RFC have zero chance, try to be in my place, alone versus giant contributor who attack everything you will do even trying your best. Thus, I take the position to not expect anything from this cause I didn't want to get hurt even if it's already the case and I half wish to come back to the past to prevent me from making the first RFC cause my project who was using a rocket pre-release break without reason.

But if it's accept or if you try to help me to make it happen I will of course help, but I will not fight to impose this even if I think it's better, that why I say I didn't make it to be a "Success " aka "accepted RFC" my point was to present problems, present working and elegant solution, that all. Not to try to impose theses solutions.

I was not making a statement on whether you overlooked something but that the discussion of the RFC is likely to overlook something. I've seen this in another RFC where one area got the focus of discussion overshadowing discussions on other areas.

Well, I can't really "split" this RFC, imagine splitting SemVer 2 RFC, I can try but I think it would be worse, I tried to make the RFC the more easy to read than I could. I could maybe remove the part about guideline for pre-release policy.

I am unsure of the value of it; I'm intentionally not reviewing it yet until we have a break down of what should be done so as not to be distracted by the minutia as we resolve more pressing questions.

I also think this is not urgent, I will improve the RFC over time, try to take into account peoples review. I have already spot some little typo and unclear sentence.

[Stargateur]

I will try to work to split the RFC into smaller part.

[Stargateur]

@CAD97

FWIW I personally think this is a better definition for ~ ignoring backwards compatibility and matching other ecosystems' behavior, but I also value backwards compatibility more.

I think I should have critic current ~ way more, actually, I miss understand what this operator was doing so much at first. The current behavior of ~ just don't have any logic, just 3 arbitrary rules.

Addition of ||, potentially &&, ()

Hard to say but I think I advice to never add () or && for a Rust SemVer 1.1, we add ||, make depreciation warning for everything removed in Rust SemVer 2. && would make no sense in my proposition, it will defeat the purpose to be simple and avoid user mistake of "raw" range.

Redefinition of versions considered compatible within pre-releases
Redefinition of how requirement operators work when pre-release versions are present

I must really insist on semver/semver#584 (comment) warning about security concern to change rule without opt in.

FWIW I personally think this is a better definition for ~ ignoring backwards compatibility and matching other ecosystems' behavior, but I also value backwards compatibility more.

Well, that why I call it 2, ^^, I think we can have a tool to "upgrade" from Rust SemVer 1 to 2. But I'm not sure it's a good idea, users should read the new rules (thus these rules need to be explain with better words than mines in cargo documentation)

[joshtriplett]

We discussed this in today's @rust-lang/cargo meeting.

We felt like this RFC is trying to do too many things at once.

We'd like to see one RFC that just proposes removing things, but doesn't add anything new. We'd also like that RFC to tie it to edition, rather than adding a separate option; for instance if a project's Cargo.toml specifies edition = "2024", it can't use those removed things.

(Also, please don't call this "SemVer 2"; that's really confusing given that SemVer version 2 is a thing that exists and isn't related to this. Please call this something like "Removing some semver operators in a future edition".)

Separate from that, if we want to add new operators, we'd want those to be a separate proposal. And a sketch of that proposal should be discussed and roughly approved of before it becomes a full RFC.

@rfcbot close

[rfcbot]

Team member @joshtriplett has proposed to close this. The next step is review by the rest of the tagged team members:

• @Eh2406
• @ehuss
• @epage
• @joshtriplett
• @weihanglo

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This is now closed.