README: what rand is / is not

README.md

@@ -8,19 +8,41 @@
 [![API](https://docs.rs/rand/badge.svg)](https://docs.rs/rand)
 [![Minimum rustc version](https://img.shields.io/badge/rustc-1.36+-lightgray.svg)](https://github.com/rust-random/rand#rust-version-requirements)
 
-A Rust library for random number generation.
-
-Rand provides utilities to generate random numbers, to convert them to useful
-types and distributions, and some randomness-related algorithms.
-
-The core random number generation traits of Rand live in the [rand_core](
-https://crates.io/crates/rand_core) crate but are also exposed here; RNG
-implementations should prefer to use `rand_core` while most other users should
-depend on `rand`.
+A Rust library for random number generation, featuring:
+
+-   Easy random value generation and usage via the [`Rng`](https://docs.rs/rand/*/rand/trait.Rng.html),
+    [`SliceRandom`](https://docs.rs/rand/*/rand/seq/trait.SliceRandom.html) and
+    [`IteratorRandom`](https://docs.rs/rand/*/rand/seq/trait.IteratorRandom.html) traits
+-   Secure seeding via the [`getrandom` crate](https://crates.io/crates/getrandom)
+    and fast, convenient generation via [`thread_rng`](https://docs.rs/rand/*/rand/fn.thread_rng.html)
+-   A modular design built over [`rand_core`](https://crates.io/crates/rand_core)
+    ([see the book](https://rust-random.github.io/book/crates.html))
+-   Fast implementations of the best-in-class [cryptographic](https://rust-random.github.io/book/guide-rngs.html#cryptographically-secure-pseudo-random-number-generators-csprngs) and
+    [non-cryptographic](https://rust-random.github.io/book/guide-rngs.html#basic-pseudo-random-number-generators-prngs) generators
+-   A flexible [`distributions`](https://docs.rs/rand/*/rand/distributions/index.html) module
+-   Samplers for a large number of random number distributions via our own
+    [`rand_distr`](https://docs.rs/rand_distr) and via
+    the [`statrs`](https://docs.rs/statrs/0.13.0/statrs/)
+-   [Portably reproducible output](https://rust-random.github.io/book/portability.html)
+-   `#[no_std]` compatibility (partial)
+-   *Many* performance optimisations
+
+It's also worth pointing out what `rand` *is not*:
+
+-   Small. Most low-level crates are small, but the higher-level `rand` and
+    `rand_distr` each contain a lot of functionality.
+-   Simple (implementation). We have a strong focus on correctness, speed and flexibility, but
+    not simplicity. If you prefer a small-and-simple library, there are
+    alternatives including [fastrand](https://crates.io/crates/fastrand)
+    and [oorandom](https://crates.io/crates/oorandom).
+-   Slow. We take performance seriously, with considerations also for set-up
+    time of new distributions, commonly-used parameters, and parameters of the
+    current sampler.
 
 Documentation:
+
 -   [The Rust Rand Book](https://rust-random.github.io/book)
--   [API reference (master)](https://rust-random.github.io/rand)
+-   [API reference (master branch)](https://rust-random.github.io/rand)
 -   [API reference (docs.rs)](https://docs.rs/rand)
 
 
@@ -38,35 +60,36 @@ 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.
+Rand is *mature* (suitable for general usage, with infrequent breaking releases
+which minimise breakage) but not yet at 1.0. We maintain compatibility with
+pinned versions of the Rust compiler (see below).
 
-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:
+Current Rand versions are:
 
 -   Version 0.7 was released in June 2019, moving most non-uniform distributions
     to an external crate, moving `from_entropy` to `SeedableRng`, and many small
     changes and fixes.
--   Version 0.6 was released in November 2018, redesigning the `seq` module,
-    moving most PRNGs to external crates, and many small changes.
--   Version 0.5 was released in May 2018, as a major reorganisation
-    (introducing `RngCore` and `rand_core`, and deprecating `Rand` and the
-    previous distribution traits).
--   Version 0.4 was released in December 2017, but contained almost no breaking
-    changes from the 0.3 series.
+-   The `master` branch is close to 0.8 release.
 
-A detailed [changelog](CHANGELOG.md) is available.
+A detailed [changelog](CHANGELOG.md) is available for releases.
 
 When upgrading to the next minor series (especially 0.4 → 0.5), we recommend
 reading the [Upgrade Guide](https://rust-random.github.io/book/update.html).
 
+Rand has not yet reached 1.0 implying some breaking changes may arrive in the
+future ([SemVer](https://semver.org/) allows each 0.x.0 release to include
+breaking changes), but is considered *mature*: breaking changes are minimised
+and breaking releases are infrequent.
+
+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.
+
 ### Yanked versions
 
 Some versions of Rand crates have been yanked ("unreleased"). Where this occurs,

appveyor.yml

@@ -34,6 +34,7 @@ build: false
 test_script:
   - cargo test --tests --no-default-features
   - cargo test --tests --no-default-features --features=alloc,getrandom
+  - cargo test --features simd_support
   # all stable features:
   - cargo test --features=serde1,log
   - cargo test --benches --features=nightly