From 33002ecd58ebf14c85354e15361d329758ce4be0 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Wed, 17 Apr 2019 15:29:42 +0100 Subject: [PATCH] Add explanations of cross-version crate compatibility to README --- README.md | 9 +++++++++ rand_core/README.md | 11 +++++++++++ 2 files changed, 20 insertions(+) diff --git a/README.md b/README.md index 61c7a17fc77..244df867736 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,15 @@ To get started using Rand, see [The Book](https://rust-random.github.io/book). ## Versions +Rand libs have inter-dependencies and make use of the +[semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits +compatible across crate versions. (This is especially important for `RngCore` +and `SeedableRng`.) A few crate releases are thus compatibility shims, +depending on the *next* lib version (e.g. `rand_core` versions `0.2.2` and +`0.3.1`). This means, for example, that `rand_core_0_4_0::SeedableRng` and +`rand_core_0_3_0::SeedableRng` are distinct, incompatible traits, which can +cause build errors. Usually, running `cargo update` is enough to fix any issues. + The Rand lib is not yet stable, however we are careful to limit breaking changes and warn via deprecation wherever possible. Patch versions never introduce breaking changes. The following minor versions are supported: diff --git a/rand_core/README.md b/rand_core/README.md index e21d5a71fda..1066456105f 100644 --- a/rand_core/README.md +++ b/rand_core/README.md @@ -40,6 +40,17 @@ The `rand_core` crate provides: The traits and error types are also available via `rand`. +## Versions + +Rand libs have inter-dependencies and make use of the +[semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits +compatible across crate versions. (This is especially important for `RngCore` +and `SeedableRng`.) A few crate releases are thus compatibility shims, +depending on the *next* lib version (e.g. `rand_core` versions `0.2.2` and +`0.3.1`). This means, for example, that `rand_core_0_4_0::SeedableRng` and +`rand_core_0_3_0::SeedableRng` are distinct, incompatible traits, which can +cause build errors. Usually, running `cargo update` is enough to fix any issues. + ## Crate Features `rand_core` supports `no_std` and `alloc`-only configurations, as well as full