Tracking issue for potential breaking changes

[cuviper]

num-traits is somewhat of a de facto stable crate. Since these traits are often found in the public API of other crates, we really want to avoid the sort of ecosystem split that a breaking-change semver bump might cause.

Nevertheless, it's a good idea to track what breaking changes we might want to make someday, now found in the list below. Links are included to postponed issues, which often have more details. They will be closed in the meantime, but discussion can continue.

• Remove default epsilon implementation for Float Remove default epsilon implementation for Float #4
• Num::FromStrRadixErr should have Trait bound Num::FromStrRadixErr should have Trait bound #6
• More features for Float More features for Float #8
• All bit twiddling functions in num::traits::PrimInt should take or return usize instead of u32 All bit twiddling functions in num::traits::PrimInt should take or return usize instead of u32 #14
• std::num::Checked{Add,Sub,Mul,Div} should have type parameters std::num::Checked{Add,Sub,Mul,Div} should have type parameters #15
• Use Mul by reference in pow Use Mul by reference in pow  #18
• Make the Float trait depend on FloatConst. Make the Float trait depend on FloatConst. #20
• Add Default, Display, and Debug trait bounds to PrimInt Add Default, Display, and Debug trait bounds to PrimInt #44
• Easy conversions between Signed and Unsigned Easy conversions between Signed and Unsigned #46
• Blanket impl for Real trait prevents parameterized implementations. Blanket impl for Real trait prevents parameterized implementations. #49
• Functions to distinguish signaling from non-signaling NaN's Functions to distinguish signaling from non-signaling NaN's #51
• Bound FloatCore by Bounded? Bound FloatCore by Bounded? #55
• Implement traits for Reverse (rust 1.19+) impl Bounded for Reverse #65
• Make One::is_one a required method and remove its Self: PartialEq Add method is_one to One trait #5 (comment)
• LowerBounded and UpperBounded (Add LowerBounded/UpperBounded traits #210) should be super-traits of Bounded

[kotauskas]

I don't get why #15 is considered breaking. Rhs=Self should keep it compatible.

[cuviper]

Quoting #15:

The corresponding std::ops traits have both the type of right hand side operand and the type of result, while Checked* traits do not (and always assume that both operands and result have the same type).

I vaguely recall seeing some cases where type defaults don't fully prevent breaking changes, but I'm not sure off-hand. The result type is definitely a problem though, because associated type defaults are still unstable.

[kotauskas]

IMO the Result type should not be added just yet and still be postponed for 1.0 or future 0.x releases, and Rhs=Self, something that I really need for bigbit now, added in 0.2.x. Just sitting down and brainstorming this, I have no idea how Rhs=Self could ever break anything.

[cuviper]

Here's the breaking case I was thinking of: rust-lang/rust#69454 (comment)

[newpavlov]

How about introducing to the conversion traits try_from method in addition to from and make the latter return value instead of Option (when conversion can not be done it will panic)? It's quite annoying to write F::from(42.0).unwrap() and it makes resulting code containing many constants like this really noisy.

[kotauskas]

How about introducing to the conversion traits try_from method in addition to from

From<U> for T implies Into<T> for U, which, in turn, implies TryFrom<U> for T with Infallible as the error type, meaning that you can't implement From<U> for T and TryFrom<U> for T at the same time. Specialization should make this problem solvable if the blanket implementations are made default, but it sadly is still unstable.

[newpavlov]

I was talking primarily about the NumCast trait. Probably deprecating it in favor of From/TryFrom should be considered as well.

[frewsxcv]

num-traits is somewhat of a de facto stable crate. Since these traits are often found in the public API of other crates, we really want to avoid the sort of ecosystem split that a breaking-change semver bump might cause.

Any thoughts on when is the right time to execute these breaking changes? It is nice the crate is so stable, but also would be great to get these changes and ship a 1.0. Thoughts? I'm willing to help make these changes!

[vadixidav]

As per my comments in #197, I think we should also add Float: FloatCore as a potential breaking change.

[cuviper]

My current opinion is that we should just bump to 1.0 as-is, reflecting the status quo of an effectively stable API. We would publish re-exports in 0.2.x for compatibility, just as the transition from 0.1 was managed (the "semver trick").

The changes in this list would all be for a potential 2.0, but I don't know if there's a right time to do that. I fear it will be really painful. It also doesn't help that I'm the only active maintainer here, and I don't have much time for it -- the refactors we all want would probably overwhelm me just to review...

[newpavlov]

@cuviper
The crate has known issues which can not be fixed without a breaking release. Personally, I would strongly prefer if first num-traits v0.3 with necessary changes was released first and only if it will require no breaking changes for a certain amount of time (e.g. one year), release it as v1.0 via semver trick.

Cutting a 1.0 release because you don't have enough time to work on the crate is not a great practice in my opinion, especially for a core crate. Maybe you could attract additional maintainers via announcement on URLO/Reddit/etc?

[frewsxcv]

The changes in this list would all be for a potential 2.0, but I don't know if there's a right time to do that. I fear it will be really painful. It also doesn't help that I'm the only active maintainer here, and I don't have much time for it -- the refactors we all want would probably overwhelm me just to review...

It's a lot of work growing a community! Thank you so much for all your contributions thus far, so much of the Rust community (and now for-profit companies) depend on your work and it's going unappreciated.

What support and help can we give to help ship a new release with breaking changes? Which parts of releasing fill you with the most dread?

[cuviper]

@frewsxcv I think even before we contemplate breaking changes, I need to get more maintainers on board -- not that I will be going away, but I shouldn't be doing this alone. And that's largely on me, that I haven't fostered anyone else into the project, but I don't think it's an easy thing regardless.

@newpavlov

Maybe you could attract additional maintainers via announcement on URLO/Reddit/etc?

I don't think it's as simple as that, because there's a large degree of trust required, especially for a crate with such wide use. Frankly, I also don't have the time to mentor a bunch of eager new rustaceans as maintainers, as nice as that might be, since I'm not even keeping up with issues and pull requests right now. I know there's a tipping point where new maintainers reduce the rest of that load, but we have to get over that hump.

But I recognize the need to break this gridlock. The two of you are both well-established maintainers in the Rust ecosystem -- would you be interested in joining @rust-num and helping out? Whether for just this crate or for the whole suite, let me know. I'll keep this door cracked if other experienced folks are interested too.

PS: I fear that I may get flak about gatekeeping or similar, so I want to emphasize that contributions are welcome from anyone, regardless of experience. It's only maintainership that needs a higher bar, and new contributors will have a longer road of establishing their own track record. This twitter thread also captures some of that sentiment.

[Elizafox]

I know I'm just a rando, but if I may make a suggestion, perhaps you could namespace breaking traits as a stopgap? It's less maintainership burden, doesn't involve the burden of supporting multiple releases, and solves the immediate problem.

maybe like num-traits::experimental:: etc. Once things there are stabilised, and you're ready to release them, you can release them as the defaults in 0.3.x or whatever.