Release 0.3?

[josephlr]

We have a few changes coming up (#425, #414 , #432) which will make the following changes to the compatibility of this crate:

• Increase the Minimum Supported Rust Version (MSRV) from 1.36 (released July 4, 2019) to 1.56 (released October 21, 2021).
• Increase the supported OS version of *-pc-windows-{gnu,msvc} from Windows Vista (released November 30, 2006) to Windows 10 (released July 15, 2015).
  • Rust increased its minimum Windows OS version from Windows 7 to Windows 10 in February 26th, 2024.
  • Older versions of Windows are still supported under the x86_64-win7-windows-msvc and i686-win7-windows-msvc targets
  • We would intend to continue to support the *-win7-* targets (via RtlGenRandom)
• We are not making any changes to the API of this crate
• We are not making any changes to the features of this crate

The Rust Semver Compatibility Guide does not specify if such actions would be breaking changes. Both:

• changing the minimum version of Rust required
• changing the platform and environment requirements

are listed as "Possibly-breaking" changes.

My personal preference would be to release these changes as 0.2.16 (not consider this a breaking change) because:

• getrandom is widely used throughout the Rust ecosystem so updating all callers can be somewhat tedious.
• It's not clear how a user can have a custom implementation work with both versions of getrandom.
• Both the MSRV increases and the Windows platform increases are less disruptive than an Semver-breaking change.

However, if we do decide to have this be a breaking change, we should discuss if there are any other semver-breaking changes we wish to make (see #346 and #230). Another option would just be to get consensus on #232 and release these changes as 1.0

[josephlr]

CC: @dhardy @vks for how this might affect rand

[newpavlov]

We are not making any changes to the API of this crate

There was a proposal to rename getrandom(_uninit) to fill(_uninit), plus there is #365, but I do not have a concrete proposal for it now. Associated Error constants could also use a bit of work, e.g. I am not sure it's worth to expose constants like VXWORKS_RAND_SECURE on all platforms. We also can use this release to reconsider our cfgs (e.g. #230 and #346). It's also worth to tweak __getrandom_custom's signature to remove this hack.

Moreover, we can use this release to relax our MSRV policy in the vein suggested by @briansmith, but this should be done together with rand.

getrandom is widely used throughout the Rust ecosystem so updating all callers can be somewhat tedious.

I think it's rarely used directly, usually it's done through rand crates.

It's not clear how a user can have a custom implementation work with both versions of getrandom.

It's possible to do this:

[dependencies]
getrandom02 = { version = "0.2", package = "getrandom" }
getrandom = "0.3"

And call the registering macros from each crate (assuming extern functions are called differently).

[dhardy]

As @josephlr says, pushing these changes to a 0.2.x release does not break any formal stability guarantees and likely won't cause a large number of issues, though it's impossible to be certain.

I have a slight preference for bumping the version to 0.3 since the drawbacks are small:

• Custom backends can support multiple versions of getrandom as @newpavlov says. An example of this in action: winit supports three versions of raw-window-handle (optionally).
• No other dependants will be affected. Some build trees may end up using multiple getrandom versions, but this hardly matters.

[briansmith]

• No other dependants will be affected. Some build trees may end up using multiple getrandom versions, but this hardly matters.

I understand what you're saying, but in practice it does matter. Many people have their CI set up to reject multiple versions of a dependency by default. so they have to either make an exception to their CI rules, and/or they submit PRs upstream to try to upgrade everybody to the new version, which is extra work for everybody. Then those upstream projects (such as some I maintain) end up having to choose to drop support for 0.2 to help these people, or spend time trying to explain to them (over and over, indefinitely) why it "hardly matters." Either way it ends up being disproportionate amount of effort.

If we release 0.3:

• What will we cap the MSRV to for the 0.3 series? 1.63 and insist on a 0.4 for any higher MSRV? Otherwise, I guess many projects will want to stick with 0.2.
• When we add new OS support for 0.3, will we backport those to 0.2? In general will we keep maintaining 0.2? Depending on the MSRV policy for 0.3, there is likely going to be pressure to maintain 0.2.

[briansmith]

There was a proposal to rename getrandom(_uninit) to fill(_uninit),

It would be nice but (a) it can be done in a backward-compatible way by renaming it to fill and providing a wrapper named getrandom[_uninit] that is optionally marked #[deprecated].

#365

I think nonblocking getrandom should be a separate API and so it could be added in a SemVer-capable manner. And/or we could implement the old API in terms of the new API, optionally eventually marking the old API #[deprecated].

Associated Error constants could also use a bit of work, e.g. I am not sure it's worth to expose constants like VXWORKS_RAND_SECURE on all platforms.

Better to discuss it in its own issue to reach a decision.

We also can use this release to reconsider our cfgs (e.g. #230 and #346). It's also worth to tweak __getrandom_custom's signature to remove this hack.

Yes, these are basically bugs that we've deferred fixes for until we make a SemVer-breaking version bump, so we should do this for 0.3.

[josephlr]

I opened #438 and #439 to discuss breaking changes to the API and feature flags respectively. I'm convinced by the arguments above, we should release these changes as a breaking change.

• What will we cap the MSRV to for the 0.3 series?

Personally, I think that we should cap the MSRV for the upcoming release at 1.57 (1.56 is Rust 2021, and 1.57 gives us panicking in const which is super nice for static checks). My preference would actually be to release these upcoming changes as 1.0. I know @newpavlov wants to wait for MSRV-aware dependency resolution, but I'm not sure why we should block releasing 1.0 on that feature.

For 1.0 and onward, we can just say that removing platform support and increasing the MSRV can be done in a minor version, and that:

• we won't drop platform support until Rust libstd does
• our MSRV will always be "conservative" (maybe 2 years of old compiler versions?)

That way folks can put getrandom = "1.0" in their dependency file if they are fine with an MSRV of "2 years ago" and if they really want to for-sure not be broken, they can do getrandom = "~1.0"

• When we add new OS support for 0.3, will we backport those to 0.2? In general will we keep maintaining 0.2? Depending on the MSRV policy for 0.3, there is likely going to be pressure to maintain 0.2.

I really wouldn't want to bother back-porting changes. I think we could have backports be "contributions welcome". I'd be fine reviewing backports, but I don't want to do the backporting (especially if nobody's actually using it).

[newpavlov]

I don't think we should release v1.0, not only because of the MSRV-aware resolver, but also because we will introduce new APIs. There are also potential for new features like "global crate features", which can be quite useful for us. Remember that we always can use the semver trick to release v0.3-compatible v1.0, assuming the APIs stay stable enough.

I really wouldn't want to bother back-porting changes. I think we could have backports be "contributions welcome". I'd be fine reviewing backports, but I don't want to do the backporting (especially if nobody's actually using it).

I agree with this, IIRC we acted similarly with v0.1 backports.

[briansmith]

The main problem with trying to make the next release be 1.0: The release will be long-delayed because there's too much perfecting and too many potential compatibility-breaking changes.

I think we need to accept the MSRV increases for 0.2 and do a 0.2 release soon, so that we don't get into a state where we can't do a release because master isn't good enough to be 1.0.

[newpavlov]

@josephlr
FYI I temporarily disabled the review requirement as we discussed in the email. Unreviewed changes start from this commit and have to reviewed before we release v0.3.

[dhardy]

To reply to @newpavlov here instead of in #544:

@dhardy My plan is to release getrandom v0.3 before before rand v0.9. You will not be able to silently migrate from v0.2 to v0.3 even with rust-random/rand#1537 because of the changes around optional backend handling.

So there are breaking changes, but not in the API. We already tell people using rand to use a direct dependency on getrandom when needing to customise the implementation so in a certain sense it would not be a breaking change to update getrandom, but on the other hand it could still cause issues.

I'd like to be able to release rand v1.0 soon after v0.9; I don't know if getrandom has plans for 1.0 soon?

[newpavlov]

I think we could release v1.0 relatively soon (in a year or two after the v0.3 release) assuming no issues will be found with the new APIs. One thing which I would like to do with v1.0 (here and with rand) is to migrate to the 2024 edition and relax our MSRV policy by telling users to rely on the new MSRV-dependent resolver. But since it involves a substantial MSRV bump, I don't think we should rush it.