This is an automated email from the ASF dual-hosted git repository. aherbert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-rng.git
commit 2ffe262e5c4504b9f16bb9bf94fbbe195da394ab Author: Alex Herbert <[email protected]> AuthorDate: Sun Mar 20 21:36:01 2022 +0000 Document the lack of functional compatibility for derived output types. Only the reference output type (int/long) from the generator is required to maintain functional compatibility. --- .../org/apache/commons/rng/core/package-info.java | 9 ++++++++ src/changes/changes.xml | 5 +++++ src/site/apt/userguide/rng.apt | 24 +++++++++++++++++++++- src/site/xdoc/userguide/index.xml | 8 ++++++-- 4 files changed, 43 insertions(+), 3 deletions(-) diff --git a/commons-rng-core/src/main/java/org/apache/commons/rng/core/package-info.java b/commons-rng-core/src/main/java/org/apache/commons/rng/core/package-info.java index dde44cb..3abf3b0 100644 --- a/commons-rng-core/src/main/java/org/apache/commons/rng/core/package-info.java +++ b/commons-rng-core/src/main/java/org/apache/commons/rng/core/package-info.java @@ -40,6 +40,15 @@ * values are defined in the * {@link org.apache.commons.rng.core.source64 source64} package. * </p> + * + * <p> + * Implementations are expected to match an algorithm reference output + * for the source output type (32-bit or 64-bit integers). This should + * be maintained across release versions. Output for derived types + * obtained from the source output type, such as float or boolean, are + * not required to maintain functional compatibility to allow algorithm + * improvements. + * </p> * * <p> * Each implementation must have an identifier in diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 0926c7f..e2db3d1 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -80,6 +80,11 @@ probability. The 'maven-surefire-plugin' is configured to re-run tests that fail, and pass the build if they succeed within the allotted number of reruns (the test will be marked as 'flaky' in the report). + +The source output type (int/long) of a RNG must maintain +behavioural compatibility between releases; derived types +may break behavioural compatibility. Any functional changes +will be recorded in the release notes. "> <action dev="aherbert" type="update" issue="171"> Recuce the memory footprint of the cached boolean and int source for the IntProvider diff --git a/src/site/apt/userguide/rng.apt b/src/site/apt/userguide/rng.apt index d62523c..9476d58 100644 --- a/src/site/apt/userguide/rng.apt +++ b/src/site/apt/userguide/rng.apt @@ -1006,6 +1006,28 @@ java -jar target/examples-jmh.jar -h Details of each example module is contained in a <<<HOWTO.md>>> document in the module directory. -7. Dependencies +7. Release compatibility + + Apache Commons RNG will maintain binary compatibility within a major release number. + However the <output> from a random generator <may differ> between releases. This is a functional + compatibility change. The result is that when upgrading the library any code based on a + random generator may produce different results. For example any unit test code written + with a fixed seed to generate pseudo-random test data may fail after update as the test data + has changed. + + The library generators are algorithms that produce a stream of random bits using 32-bit or + 64-bit integer output. The output from the primary type will maintain functional compatibility + for the lifetime of the library. This output is tested to match a reference implementation + of the algorithm and should be invariant. The only exception is to address bug fixes identified + in the upstream implementation. + + The primary output of the generator is used to produced derived types, for example floating + point values, byte arrays and integers within a range. The output for derived types is not + subject to functional compatibility constraints. Put simply the output from a generator may + be different even when using the same starting seed due to updates to generation algorithms + that use the underlying stream of random bits. Any library changes that result in a + functional compatibility should be recorded in the release notes. + +8. Dependencies Apache Commons RNG requires JDK 1.8+ and has no runtime dependencies. diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml index b692c8e..2fceed1 100644 --- a/src/site/xdoc/userguide/index.xml +++ b/src/site/xdoc/userguide/index.xml @@ -53,8 +53,12 @@ 6. Examples</a> </li> <li> - <a href="rng.html#a7._Dependencies"> - 7. Dependencies</a> + <a href="rng.html#a7._Release_compatibility"> + 7. Release compatibility</a> + </li> + <li> + <a href="rng.html#a8._Dependencies"> + 8. Dependencies</a> </li> </ul>
