Release strategy

[dhardy]

Hello people,

so I've effectively become the current maintainer of rand; @alexcrichton has now given me permission to push out new releases too. This issue is to clarify my plans with the various people watching/contributing here and get some feedback.

First up, I won't be directly merging my branch. It contains a lot of changes, some of which need further review and further tweaking. It exists more as a preview of roughly where we're aiming, and to allow development using the new error type. Quite a lot of what's in this branch depends on the new error type and changes to the Rng trait, and merging those into rand now would be quite a significant breaking change — and one that might change more, since some items should get pushed to the rand-core crate, and this still needs some development before RFC approval (dhardy#18 being the main unsolved issue).

That brings me to the topic of releases. @est31 has requested a new release with a minor change. There are multiple ways we could do this:

• Conservative: backport desired non-breaking changes to 0.3, hold off on 0.4 for now. [Not preferred due to requirement to maintain an extra branch and make more merges; also due to long delay before releasing most changes.]
• Eager: release 0.4 with current changes, have no qualms about releasing 0.5, 0.6, ..., 0.20, etc. given small breaking changes.
• Unstable series: release 0.4 and document it as "unstable" for the time being, keep pushing breaking changes there.
• Hybrid: continue making "patch" releases with new features (tracking the master branch closely) but avoid all API breakage.

Personally, I prefer the idea of using an unstable series. It's not strictly SemVer but works well with the RERO philosophy: we consider 0.3 stable and only make minimal (if any) changes, while 0.4 is considered unstable until some point in the future where we fix it and stop making significant changes.

There is also the question of what exactly constitutes a breaking change. In theory a deprecation is just a warning that some thing will be removed in the future, but some people I've worked with in the past interpret compiler warnings as serious issues which must be solved immediately, which makes introducing deprecations themselves problematic. There are also changes which are difficult to fully test, e.g. the new JitterRng is highly platform dependent. I think therefore it may be best to initially release all deprecations and significant new features in a new or existing unstable channel (i.e. eager or unstable series strategy above).

Any thoughts, questions? Can't say too much about time-line, but this all takes time (especially allowing for reviews).

[est31]

I personally could live with any approach, as I'm only including rand at the top of my dependency tree, so I have full control over which version I am using. What I would like is to have some kind of a release soon, meaning in the next few days. That would be wonderful!

For one of my projects I ended up having separate branches (conservative approach), to fix some important issue, but then reverted back to the eager approach which I usually follow. I do have only few reverse dependencies though, unlike rand, so the eager approach is feasible for me as it only causes little churn :).

[pitdicker]

First: congratulations 🎉 . I will try to support you a little.

I feel somewhat mixed about the release strategies. A couple of point updates to 0.3 just seem necessary.

I would really like to see a release with all the improvements we are making. It is not great to make all kinds of changes with no real libraries using it. We may make a mistake and not notice it for weeks/months. So I like an unstable series.

A problem with eager is that I don't think we have much budget for releasing versions with breaking changes. I would say not more than two times in the next year. And there may be quite a few areas yet where we could improve, but not backward-compatibly.

Conservative and hybrid assume we can make improvements but end up backward-compatible. What we are improving now is error handling, traits, algorithms and choice of RNG's. All are not compatible...

Does Cargo/Semver support something like unstable series? Advertising them as 0.4 would make new crates depend on 0.4 (the latest version) by default. And I don't think an unstable version is a good default. Does something like 0.4.0-alpha.1 work? See rust-lang/cargo#2222

[dhardy]

Thanks.

Releasing 0.4 as unstable would require users not wanting to update to change their version specification; looks like ^0.3 should work according to the docs. I don't know if appending alpha/beta/rc suffixes work; after all 0.x is always considered unstable by semver.

No, I'm not sure that the eager approach would help users. Conservative and hybrid make our job harder and hold back features.

[dhardy]

Pre-release suffixes (like 0.4.0-pre.0) aren't handled consistently, e.g.: dtolnay/semver#128, dtolnay/semver#124

Semver itself doesn't appear to have any documentation on handling pre-release suffixes when the major version number is 0, and the Rust semver crate has no test cases. Because of this I'm very reluctant to use this functionality. (I may make a PR against semver; not sure what'll happen though.)

[pitdicker]

Hmm, that is not great. Still, support seems good enough as long as crates use 0.4.0-rc or 0.4.0-rc.2 as version requirement.

Will improving the semver crate help us (although improvements are always good)? It will take months (?) until most Rust installations have the new version.

[dhardy]

After diving into the rules, I think we can use something like 0.4.0-unstable.0 and users will not upgrade to it unless explicitly mentioning some suffix (e.g. ^0.4.0-a should match but ^0.4.0 won't). Cargo doesn't quite follow upstream semver, so rules implicitly start with ^ unless = or another operator is specified. So I may still try to fix semver but it's not important.

[dhardy]

Okay, I bumped the version number to 0.4.0-pre.0 and added a note to the readme; this should do for the next release.

I'm not sure whether to make the next stable version 0.4.0 or 0.4.1; currently a requirement on 0.4.0-pre.0 would also match 0.4.0 but this might change (see dtolnay/semver#124 and the PR I made). Either way 0.4.0 will not match anything with a -pre or other suffix; so not too big a deal, but going straight to 0.4.1 may be less confusing.

[dhardy]

0.4.0-pre.0 is published. We could backport some stuff (like the WASM and JitterRng) to 0.3.x but I'm not sure I see a lot of point. We can continue pushing new features to 0.4.0-pre.x for now, then when we're ready push out 0.4.1 as a stable release (and possibly make a 0.5.0-pre.x unstable series).

[nox]

I don't understand the point of doing prereleases, when you could just make a new release every time there is a breaking change, this crate isn't even in 1.0.0 yet, so why bother with the added complexity.

I also don't understand why 0.4.0-pre.x should become 0.4.1 instead of 0.4.0 when it's ready.

From Cargo and semver's POV, 0.4.0-pre.x doesn't match 0.4.0 anyway.

[dhardy]

The only point is that we will make quite a few breaking changes and don't want to annoy people with 0.4.7 breaking stuff, or making 0.5, ... 0.12 etc.

Yes, 0.4.0-pre.x could become 0.4.0 in theory, but Semver doesn't make it clear which is considered to come first, semantically, and hence I'm uncertain whether it will change. (If you are sure about this please comment.)

[nox]

What I don't understand is, what is wrong with releasing 0.12?

[dhardy]

Nothing, maybe... hence why I created this issue to ask.

[pitdicker]

@dhardy can you describe how you imagine an unstable series? I imagined your branch was going to become that. Or will you cherry-pick some op the open PR's here and some of commits on your branch?

I would prefer your branch as unstable series (maybe with a few of the trait alternatives removed). Otherwise we end up with three 'important' branches.

[dhardy]

@pitdicker I was thinking of merging small chunks of code from my branch and making a new release each time.

It may be better however to just make 0.4.0-pre.0 into 0.4.0, then make a big PR as a potential 0.5.0.

In which case, what do people think of me making a 0.5.0-pre.0 release based on the contents of a PR? This would make it much easier for people to test the PR code without causing too many issues if the PR ends up not landing or having significant changes, I think.

[est31]

In which case, what do people think of me making a 0.5.0-pre.0 release based on the contents of a PR?

I don't think this is a good idea. You can do testing with git dependencies as well. crates.io is an add-only archive of crates. So if you want feedback on PRs, direct people to use git dependencies on the PR creator's repo. There are tools in cargo to override dependencies.

[pitdicker]

I was thinking of merging small chunks of code from my branch and making a new release each time.

That sounds like a lot of work, and I don't really see the benefit. Who or what goal are we serving with these intermediate releases?

Or is your goal to carefully review the changes for breaking changes etc. (b.t.w. have there already been any yet)?

Or are there important changes that have to happen now and a breaking 0.4.0 version is needed? And then most of the new work would go into 0.5.0-pre.0?

It see no reason not to spend some weeks on 0.4.0-pre.0 to merge as much as possible and do a little clean-up, but I am probably missing something.

[est31]

I think generally the default setting should be that there are breaking releases at larger time spans (months apart), and minor releases separated by weeks or so. But if users request a backport of a feature to an older branch, or a new breaking release, one should be done IMO.

[bluss]

I would vote that you should lay out to take rand down the regular road: Release 0.4, 0.5, etc whenever there are breaking changes. It's better to get going with the evolution of the crate instead of stagnating. The third alternative would be to design a perfect 1.0 in one try, but the evolution route is more realistic.

[dhardy]

I guess you're right. There are three PRs up for review now (not sure how long to wait / if they will get extra review) which can land as 0.4.x point releases:

• no_std support Add no_std build support #208
• PRNG code improvements Cherry-pick changes to PRNG algorithms #209
• Add HC-128 (but not make it default) Add HC-128 #210

Then I suppose 0.5 could:

• Introduce the new error types
• Update Rng and add Sample and CryptoRng
• Update SeedableRng (without from_hashable) and add SeedFromRng
• Rename IndependentSample → Distribution and remove Sample trait

Then in 0.6 or 0.7:

• Update to new distributions code (Distribution trait, range code, uniform and default distributions)
• Replace Rand with a minimal wrapper on top of Default distribution (see Select "SimpleRand" over generic "Rand" for backwards compatibility dhardy/rand#71)
• Launch rand-core crate (if we still have a reason to make it separate)

And some smaller bits somewhere along the line:

• Add SeedableRng::from_hashable (possibly)
• Update choose / Choice code

[Lokathor]

Please keep rand-core separate, minimal, and nostd / wasm compatible. Being able to write code that just depends on rand-core and then having the user pick how they want to fulfill it is very good.

[dhardy]

Bear in mind that rand itself is now no_std and WASM compatible. But I am not against a separate rand-core. If you have more arguments/rationales on this topic better to put them somewhere more on topic if possible, e.g. dhardy#15 or a new issue.

[dhardy]

Closing; I think this has mostly served its purpose. Feature tracking has moved to #232.