From 216077d287b6576d088fc7e818c42e8d4c2546d7 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Sat, 20 Jul 2024 15:47:14 +0100 Subject: [PATCH] Update policy on reproducibility --- src/crate-reprod.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/crate-reprod.md b/src/crate-reprod.md index 2e13d4f..8a8a712 100644 --- a/src/crate-reprod.md +++ b/src/crate-reprod.md @@ -4,13 +4,13 @@ Given fixed inputs, all items (should) fall into one of three categories: -- Output is non-deterministic, thus never reproducible -- Output is deterministic, but not considered portable -- Output is deterministic and portable +- Output is non-deterministic, thus never reproducible (example: `rand::thread_rng`) +- Output is deterministic, but not considered portable (`SmallRng`, `StdRng`; limitations below) +- Output is deterministic and portable (named RNGs; most distributions, sampling and shuffling algorithms) In general, functionality is considered deterministic and portable *unless* it is clearly non-deterministic (e.g. `getrandom`, `ThreadRng`) *or* it is -documented as being unportable (e.g. `StdRng`, `SmallRng`). +documented as being nonportable (e.g. `StdRng`, `SmallRng`). ## Crate versions @@ -26,10 +26,11 @@ Additionally, we must also consider *value-breaking changes* and *portability*. When given fixed inputs, - For non-deterministic items, implementations may change in any release -- For deterministic unportable items, output should be preserved in patch +- For deterministic nonportable items, output should be preserved in patch releases, but may change in any minor release (including after 1.0) -- For portable items, any change of output across versions is considered - equivalent to an API breaking change. +- For portable items, output should be preserved by patch releases. + Minor releases (including after 1.0) may include such value-breaking + changes, though these must be documented in the CHANGELOG. ### Testing