Beyond API stability, we already have some docs on which functions are value-stable, e.g.:
from_seed should be value-stable (on value-stable PRNGs)StdRng and (currently at least) from_rng is not value-stable
The point of this issue is to decide when a change to an existing function affecting internal state or output values but not the API is a breaking change, and how to document which functionality is value-stable.
Proposal: add something like this to the doc:
A function is reproducible when, given equivalent input parameters (including self but excluding global variables, shared memory and system calls), all output parameters (including the value of any modified state) are equivalent (roughly meaning that they compare equal and that any further calls to public functions on these values produce equivalent output).
A library-provided function is value-stable when:
- its API does not change
- it is reproducible across calls, processes and platforms
- any change affecting reproducibility across library versions is considered a breaking change (we do not go into release policy here, but this generally implies bumping at least the minor version and a clear note in the changelog)
A trait-function is value-stable when all implementations are expected to be value-stable, excepting when the type the function is declared on is explicitly declared to not be value-stable.
A type is value-stable when it meets the value-stability requirements of all traits it implements.
Is this clear enough or does it need extra spelling-out, e.g. that value-stability of RngCore functions implies that we cannot change how many bytes get dropped if calling fill_bytes on a 1-byte array then next_u32?
With that we can start to define which functionality is value-stable; within rand_core this should include at least all of RngCore, SeedableRng::from_seed and possibly all of the impls and le modules.
Beyond API stability, we already have some docs on which functions are value-stable, e.g.:
from_seedshould be value-stable (on value-stable PRNGs)StdRngand (currently at least)from_rngis not value-stableThe point of this issue is to decide when a change to an existing function affecting internal state or output values but not the API is a breaking change, and how to document which functionality is value-stable.
Proposal: add something like this to the doc:
A function is reproducible when, given equivalent input parameters (including
selfbut excluding global variables, shared memory and system calls), all output parameters (including the value of any modified state) are equivalent (roughly meaning that they compare equal and that any further calls to public functions on these values produce equivalent output).A library-provided function is value-stable when:
A trait-function is value-stable when all implementations are expected to be value-stable, excepting when the type the function is declared on is explicitly declared to not be value-stable.
A type is value-stable when it meets the value-stability requirements of all traits it implements.
Is this clear enough or does it need extra spelling-out, e.g. that value-stability of
RngCorefunctions implies that we cannot change how many bytes get dropped if callingfill_byteson a 1-byte array thennext_u32?With that we can start to define which functionality is value-stable; within
rand_corethis should include at least all ofRngCore,SeedableRng::from_seedand possibly all of theimplsandlemodules.