Skip to content

Commit 686ba14

Browse files
dhardydhardy
authored
Merge pull request rust-random#544 from dhardy/doc
Doc and policies
2 parents d162a5e + e67423a commit 686ba14

File tree

2 files changed

+151
-3
lines changed

2 files changed

+151
-3
lines changed

‎README.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@ The core random number generation traits of Rand live in the [rand_core](
1616
https://crates.io/crates/rand_core) crate; this crate is most useful when
1717
implementing RNGs.
1818

19-
API reference:
20-
[master branch](https://rust-lang-nursery.github.io/rand/rand/index.html),
21-
[by release](https://docs.rs/rand/0.5).
19+
Documentation:
20+
- [API reference for latest release](https://docs.rs/rand/0.5)
21+
- [API reference for master branch](https://rust-lang-nursery.github.io/rand/rand/index.html)
22+
- [Additional documentation (subdir)](doc/README.md)
23+
2224

2325
## Usage
2426

‎doc/README.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Rand Documentation
2+
3+
Also see the [main project readme](../README.md).
4+
5+
## Learning Rand
6+
7+
TODO. In the mean-time, we have some learning resources within the API
8+
documentation.
9+
10+
The following example programs may be of interest:
11+
12+
- [examples/monte-carlo.rs](https://github.com/rust-lang-nursery/rand/blob/master/examples/monte-carlo.rs)
13+
- [examples/monty-hall.rs](https://github.com/rust-lang-nursery/rand/blob/master/examples/monty-hall.rs)
14+
15+
## References
16+
17+
API documentation can be found:
18+
19+
- [`rand` API on docs.rs](https://docs.rs/rand/)
20+
- [`rand_core` API on docs.rs](https://docs.rs/rand_core/)
21+
- [self-published API on github.io](https://rust-lang-nursery.github.io/rand/rand/index.html) (latest code in master branch)
22+
- by running `cargo doc --no-deps --all --all-features`
23+
24+
## Project policies
25+
26+
### Open Participation
27+
28+
This project is open to contributions from anyone, with the main criteria of
29+
review being correctness, utility, project scope, and good documentation. Where
30+
correctness is less obvious (PRNGs and some type-conversion algorithms),
31+
additional criteria apply (see below).
32+
33+
Additionally we welcome feedback in the form of bug reports, feature requests
34+
(preferably with motivation and consideration for the scope of the project),
35+
code reviews, and input on current topics of discussion.
36+
37+
Since we must sometimes reject new features in order to limit the project's
38+
scope, you may wish to ask first before writing a new feature.
39+
40+
### Stability and Portability
41+
42+
We try to follow [semver rules](https://docs.npmjs.com/misc/semver) regarding
43+
API-breaking changes and `MAJOR.MINOR.PATCH` versions:
44+
45+
- New *patch* versions should not include API-breaking changes or major new
46+
features
47+
- Before 1.0, *minor* versions may include API breaking changes. After 1.0
48+
they should not.
49+
- We may make pre-releases like `0.5.0-pre.0`. In this case:
50+
51+
- although these are public versions, they are not used by default unless
52+
opting into using a pre-release on the specific `MAJOR.MINOR.PATCH`
53+
version
54+
- pre-releases are considered semantically less than their final release
55+
(e.g. Cargo may automatically upgrade from `0.5.0-pre.0` to `0.5.0`)
56+
- all pre-release versions are unstable and may make any change
57+
- we make no commitment to support users of pre-releases
58+
59+
Additionally, we must also consider *value-breaking changes* and *portability*.
60+
A function is *value-stable* if, given the same inputs:
61+
62+
- it is portable (produces the same results on all platforms)
63+
- changing the output value for some input in a new library version is
64+
considered a breaking change
65+
66+
Note that some Rand functionality is supposed to be value stable, and some
67+
functionality is supposed to be non-deterministic (i.e. depend on something
68+
external). Some functionality may be deterministic but not value-stable.
69+
70+
A trait should define which of its functions are expected to be value-stable.
71+
An implementation of a trait must meet those stability requirements, unless the
72+
object for which the trait is implemented is explicitly not value-stable.
73+
As an example, `SeedableRng::from_seed` is required to be value-stable, but
74+
`SeedableRng::from_rng` is not. RNGs implementing the trait are value-stable
75+
when they guarantee `SeedableRng::from_seed` is value-stable, while
76+
`SeedableRng::from_rng` may receive optimisations.
77+
78+
Before 1.0, we allow any new *minor* version to break value-stability, though
79+
we do expect such changes to be mentioned in the changelog. Post 1.0 we have
80+
not yet determined exact stability rules.
81+
82+
Additionally, we expect patch versions not to change the output of any
83+
deterministic functions, even if not value-stable (this is not a hard
84+
requirement, but exceptions should be noted in the changelog).
85+
86+
Defining which parts of Rand are value-stable is still in progress. Many parts
87+
of `rand_core` have some documentation on value-stability.
88+
89+
### Project Scope
90+
91+
The `rand_core` library has the following scope:
92+
93+
- the core traits which RNGs may implement
94+
- tools for implementing these traits
95+
96+
The `rand` library has the following scope:
97+
98+
- re-export all parts of `rand_core` applicable to end users
99+
- an interface to request entropy from an external source
100+
- hooks to provide entropy from several platform-specific sources
101+
- traits covering common RNG functionality
102+
- some PRNGs, notably `StdRng` and `SmallRng`
103+
- `thread_rng` auto-seeding source of randomness
104+
- conversion of random bits to common types and uses
105+
- shuffling and sampling from sequences
106+
- sampling from various random number distributions
107+
108+
Note: the scope of the project and above libraries may change. We are currently
109+
discussing moving PRNGs (#431) and distributions (#290) to other libraries or
110+
projects.
111+
112+
### Code style
113+
114+
We do not currently have many policies on style other than:
115+
116+
- neat and consistent
117+
- minimise changes which are purely stylistic, or move to a separate commit
118+
119+
Rand does **make use of `unsafe`**, both for performance and out of necessity.
120+
We consider this acceptable so long as correctness is easy to verify.
121+
In order to make this as simple as possible,
122+
we prefer that all parameters affecting safety of `unsafe` blocks are checked or
123+
prepared close to the `unsafe` code,
124+
and wherever possible within the same function (thus making the function safe).
125+
126+
### New PRNG Algorithms
127+
128+
The Rand library includes several pseudo-random number generators, and we have
129+
received several requests to adopt new algorithms into the library. We must
130+
consider such requests in regards to several things:
131+
132+
- whether the PRNG is cryptographically secure, and if so, how trustworthy
133+
such claims are
134+
- statistical quality of output
135+
- performance and features of the generator
136+
- scope of the project
137+
- reception and third-party review of the algorithm
138+
139+
In general, we expect the following, though we may make exceptions:
140+
141+
- the author of the algorithm to publish an article of some type (e.g.
142+
a scientific article or web page) introducing the new algorithm and
143+
discussing its utility, strengths and weaknesses
144+
- review of statistical quality and any special features by third parties
145+
- good performance in automated test suites like PractRand and TestU01
146+
(unless for some reason this is not expected, e.g. a mock generator)

0 commit comments

Comments
 (0)