Consider documenting MSRV policy

[matklad]

I have suspicion that this might become one of the more important crates in the ecosystem. So, it might make sense to:

• Document minimal supported rust version (MSRV)
• Document MSRV policy (how many rustc versions back are generally supported? is MSRV a semver-breaking change?)
• Add CI job for MSRV

[mgeier]

Thanks for the suggestion!

I'm very new to maintaining Rust crates, so I might need some help here ...

What version would you suggest as MSRV?
I guess the most modern thing I'm currently using is MaybeUninit, which I guess was introduced in Rust 1.36.0.

I've tried a CI setup in #6 (and it seems to work with 1.36.0). Would that check be sufficient?

What policy would you recommend?

I guess once established, the implementation should stay quite stable, maybe running on 1.36 forever?
But who knows ...

[matklad]

What version would you suggest as MSRV?

For new crates, I suggest picking the stable at the point of publishing as MSRV and then follow a policy like "at lease a year worth of Rust versions is supported (this corresponds to 8 Rust releases)".

I've tried a CI setup in #6 (and it seems to work with 1.36.0). Would that check be sufficient?

Given that there are few deps, then yes, that'd be good. If the crate have may dependencies, it might be that some dep bumps MSRV past yours. For this to not break your CI, MSRV should be tested with a specific Cargo.lock: https://github.com/matklad/once_cell/blob/0d8a1b963b08338aae44111bdd67fe3b0f35ffd6/.travis.yml#L35-L38

I guess once established, the implementation should stay quite stable, maybe running on 1.36 forever?
But who knows ...

I also feel so, but it makes sense to document something along the line of "we don't plan to aggressively bump MSRV".

[mgeier]

Thanks.

I've added paragraph about this in #9, what do you think?

I don't really want to commit to a fixed time interval, but if people insist, I can add it later.

I don't expect the MSRV to change at all, but if it does, I guess there will be a good reason, so at least a minor version bump seems adequate to me.

If the crate have may dependencies, it might be that some dep bumps MSRV past yours. For this to not break your CI, MSRV should be tested with a specific Cargo.lock

But shouldn't it break my CI?
If they bump their MSRV beyond mine, I'll have to choose to either restrict their version in my Cargo.toml (not only Cargo.lock!) or I'll have to bump my own MSRV, right?
Either way, I want to be informed about that by my CI!

[matklad]

If they bump their MSRV beyond mine, I'll have to choose to either restrict their version in my Cargo.toml (not only Cargo.lock!) or I'll have to bump my own MSRV, right?

There's no 100% correct answer here, but I'd say that changing Cargo.toml would be a bad idea. The library is responsible only for picking ranges of compatible versions, the specific versions are always chosen by the leaf application in Cargo.lock.

Let's say you build a library L, which is compatible with Rust 1.40 and uses library A, which is also compatible with 1.40. Let's say both L and A at 1.0.0 right now. Let's say now A publishes 1.1.0, which requires Rust 1.42, and you implement a new feature in L, while still using Rust 1.40, and publishing L 1.1.0

If L doesn't constrain version of A, folks building apps for 1.40 can build it using L 1.1.0 and A 1.0.0. Folks using 1.42 can use L 1.1.0 and A 1.1.0. If, however, you pin A on your side to =1.0.0, folks on 1.42 can't take advantage of A 1.1.0. If you publish L 2.0.0 instead of L 1.2.0, than folks on 1.40 can't use L at all.

Generally, the most useful things to know are:

• my crate works with latest stable compiler using all of the latest dependencies (this catches new regressions and tests the most common configuration)
• my crates works with the oldest supporting compiler, using the oldest versions of dependencies (this makes sure that you don't lie about the oldest supported versions of things).

See also rust-lang/api-guidelines#227, especially example with crossbeam

[mgeier]

OK, this is indeed more complicated than I thought ...
Thanks for the example!

Folks using 1.42 can use L 1.1.0 and A 1.1.0. If, however, you pin A on your side to =1.0.0, folks on 1.42 can't take advantage of A 1.1.0.

That's a very good point, I didn't think about this.

My remaining question is: do I need a Cargo.lock.min right now in #6, or is it enough to add it later, once a CI breakage occurs?
I only have a single dependency (cache-padded), and I don't expect MSRV changes to happen frequently.

[matklad]

I don't think you need Cargo.lock.min right now, I think just running cargo test on latest stable and MSRV should be enough.

[mgeier]

Thanks, so I guess I'm done with #6 ... except you just mentioned cargo test, which raises another question:

Should tests be included in the considerations for MSRV?

I was assuming that tests are allowed to use much more modern features, while the library itself could still have a very old MSRV.

Is that not so?

Isn't it sufficient to run cargo check on the MSRV?

[matklad]

Yeah, many folks just cargo check for MSRV

[mgeier]

OK, cool, that's settled then.

The MSRV policy has been established with #6 and #9.

Thanks a lot for your help!