From 3f191be98a0be6f99effefac480cfae84231f06d Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Mon, 9 Jul 2018 18:15:13 +0100 Subject: [PATCH 1/5] Doc: add new doc/ sub-directory with index --- README.md | 8 ++++--- doc/README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 3 deletions(-) create mode 100644 doc/README.md diff --git a/README.md b/README.md index 8158a62a5c7..dd1832b6bd4 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,11 @@ The core random number generation traits of Rand live in the [rand_core]( https://crates.io/crates/rand_core) crate; this crate is most useful when implementing RNGs. -API reference: -[master branch](https://rust-lang-nursery.github.io/rand/rand/index.html), -[by release](https://docs.rs/rand/0.5). +Documentation: +- [API reference for latest release](https://docs.rs/rand/0.5) +- [API reference for master branch](https://rust-lang-nursery.github.io/rand/rand/index.html) +- [Additional documentation (subdir)](doc/README.md) + ## Usage diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000000..da5cbe1f300 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,64 @@ +# Rand Documentation + +Also see the [main project readme](../README.md). + +## Learning Rand + +TODO. In the mean-time, we have some learning resources within the API +documentation. + +The following example programs may be of interest: + +- [examples/monte-carlo.rs](https://github.com/rust-lang-nursery/rand/blob/master/examples/monte-carlo.rs) +- [examples/monty-hall.rs](https://github.com/rust-lang-nursery/rand/blob/master/examples/monty-hall.rs) + +## References + +API documentation can be found: + +- [`rand` API on docs.rs](https://docs.rs/rand/) +- [`rand_core` API on docs.rs](https://docs.rs/rand_core/) +- [self-published API on github.io](https://rust-lang-nursery.github.io/rand/rand/index.html) (latest code in master branch) +- by running `cargo doc --no-deps --all --all-features` + +## Project policies + +### Open Participation + +This project is open to contributions from anyone, with the main criteria of +review being correctness, utility, project scope, and good documentation. Where +correctness is less obvious (PRNGs and some type-conversion algorithms), +additional criteria apply (see below). + +Additionally we welcome feedback in the form of bug reports, feature requests +(preferably with motivation and consideration for the scope of the project), +code reviews, and input on current topics of discussion. + +Since we must sometimes reject new features in order to limit the project's +scope, you may wish to ask first before writing a new feature. + +### Stability + +TODO + +### Project Scope + +TODO + +### Code style + +We do not currently have many policies on style other than: + +- neat and consistent +- minimise changes which are purely stylistic, or move to a separate commit + +Rand does **make use of `unsafe`**, both for performance and out of necessity. +We consider this acceptable so long as correctness is easy to verify. +In order to make this as simple as possible, +we prefer that all parameters affecting safety of `unsafe` blocks are checked or +prepared close to the `unsafe` code, +and wherever possible within the same function (thus making the function safe). + +### New PRNG Algorithms + +TODO From e5134e815af3b21e8327ad566e0b836aeae56e9f Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Mon, 9 Jul 2018 18:15:58 +0100 Subject: [PATCH 2/5] doc: add policy on new PRNG algorithms --- doc/README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index da5cbe1f300..02b0575150a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -61,4 +61,23 @@ and wherever possible within the same function (thus making the function safe). ### New PRNG Algorithms -TODO +The Rand library includes several pseudo-random number generators, and we have +received several requests to adopt new algorithms into the library. We must +consider such requests in regards to several things: + +- whether the PRNG is cryptographically secure, and if so, how trustworthy + such claims are +- statistical quality of output +- performance and features of the generator +- scope of the project +- reception and third-party review of the algorithm + +In general, we expect: + +- the author of the algorithm to publish an article of some type (e.g. + a scientific article or web page) introducing the new algorithm and + discussing its utility, strengths and weaknesses +- review of statistical quality and any special features by third parties +- good performance in automated test suites like PractRand, TestU01 and + BigCrush, (unless for some reason this is not expected, e.g. a mock + generator) From 36826334f7e627699545eae92b8a621be10d37c1 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Mon, 9 Jul 2018 18:32:31 +0100 Subject: [PATCH 3/5] doc: add policy on project scope --- doc/README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/README.md b/doc/README.md index 02b0575150a..d180ac940df 100644 --- a/doc/README.md +++ b/doc/README.md @@ -43,7 +43,26 @@ TODO ### Project Scope -TODO +The `rand_core` library has the following scope: + +- the core traits which RNGs may implement +- tools for implementing these traits + +The `rand` library has the following scope: + +- re-export all parts of `rand_core` applicable to end users +- an interface to request entropy from an external source +- hooks to provide entropy from several platform-specific sources +- traits covering common RNG functionality +- some PRNGs, notably `StdRng` and `SmallRng` +- `thread_rng` auto-seeding source of randomness +- conversion of random bits to common types and uses +- shuffling and sampling from sequences +- sampling from various random number distributions + +Note: the scope of the project and above libraries may change. We are currently +discussing moving PRNGs (#431) and distributions (#290) to other libraries or +projects. ### Code style From cca762cf75bd0491990a409025394f2524d95141 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Mon, 9 Jul 2018 19:00:05 +0100 Subject: [PATCH 4/5] doc: add policy on stability and breaking changes --- doc/README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/doc/README.md b/doc/README.md index d180ac940df..2e255014f3e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -37,9 +37,50 @@ code reviews, and input on current topics of discussion. Since we must sometimes reject new features in order to limit the project's scope, you may wish to ask first before writing a new feature. -### Stability - -TODO +### Stability and Portability + +We try to follow [semver rules](https://docs.npmjs.com/misc/semver) regarding +API-breaking changes and `MAJOR.MINOR.PATCH` versions: + +- New *patch* versions should not include API-breaking changes or major new + features +- Before 1.0, *minor* versions may include API breaking changes. After 1.0 + they should not. +- We may make pre-releases like `0.5.0-pre.0`. In this case: + + - although these are public versions, they are not used by default unless + opting into using a pre-release on the specific `MAJOR.MINOR.PATCH` + version + - pre-releases are considered semantically less than their stem (e.g. + Cargo may automatically upgrade from `0.5.0-pre.0` to `0.5.0`) + - all pre-release versions are unstable and may make any change + - we make no commitment to support users of pre-releases + +Additionally, we must also consider *value-breaking changes* and *portability*. +A function is *value-stable* if, given the same inputs: + +- it is portable (produces the same results on all platforms) +- changing the output value for some input in a new library version is + considered a breaking change + +Note that some Rand functionality is supposed to be value stable, and some +functionality is supposed to be non-deterministic (i.e. depend on something +external). Some functionality may be deterministic but not value-stable. + +A trait should define which of its functions are expected to be value-stable. +A type (e.g. a PRNG) is value-stable if all implementations of trait functions +for that type are value-stable where expected to be. + +Before 1.0, we allow any new *minor* version to break value-stability, though +we do expect such changes to be mentioned in the changelog. Post 1.0 we have +not yet determined exact stability rules. + +Additionally, we expect patch versions not to change the output of any +deterministic functions, even if not value-stable (this is not a hard +requirement, but exceptions should be noted in the changelog). + +Defining which parts of Rand are value-stable is still in progress. Many parts +of `rand_core` have some documentation on value-stability. ### Project Scope From e67423aebe70988ec247ba33adc1b003fba29e7e Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Thu, 12 Jul 2018 13:03:21 +0100 Subject: [PATCH 5/5] Address review comments --- doc/README.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/doc/README.md b/doc/README.md index 2e255014f3e..a2f8b624156 100644 --- a/doc/README.md +++ b/doc/README.md @@ -51,8 +51,8 @@ API-breaking changes and `MAJOR.MINOR.PATCH` versions: - although these are public versions, they are not used by default unless opting into using a pre-release on the specific `MAJOR.MINOR.PATCH` version - - pre-releases are considered semantically less than their stem (e.g. - Cargo may automatically upgrade from `0.5.0-pre.0` to `0.5.0`) + - pre-releases are considered semantically less than their final release + (e.g. Cargo may automatically upgrade from `0.5.0-pre.0` to `0.5.0`) - all pre-release versions are unstable and may make any change - we make no commitment to support users of pre-releases @@ -68,8 +68,12 @@ functionality is supposed to be non-deterministic (i.e. depend on something external). Some functionality may be deterministic but not value-stable. A trait should define which of its functions are expected to be value-stable. -A type (e.g. a PRNG) is value-stable if all implementations of trait functions -for that type are value-stable where expected to be. +An implementation of a trait must meet those stability requirements, unless the +object for which the trait is implemented is explicitly not value-stable. +As an example, `SeedableRng::from_seed` is required to be value-stable, but +`SeedableRng::from_rng` is not. RNGs implementing the trait are value-stable +when they guarantee `SeedableRng::from_seed` is value-stable, while +`SeedableRng::from_rng` may receive optimisations. Before 1.0, we allow any new *minor* version to break value-stability, though we do expect such changes to be mentioned in the changelog. Post 1.0 we have @@ -132,12 +136,11 @@ consider such requests in regards to several things: - scope of the project - reception and third-party review of the algorithm -In general, we expect: +In general, we expect the following, though we may make exceptions: - the author of the algorithm to publish an article of some type (e.g. a scientific article or web page) introducing the new algorithm and discussing its utility, strengths and weaknesses - review of statistical quality and any special features by third parties -- good performance in automated test suites like PractRand, TestU01 and - BigCrush, (unless for some reason this is not expected, e.g. a mock - generator) +- good performance in automated test suites like PractRand and TestU01 + (unless for some reason this is not expected, e.g. a mock generator)