Skip to content
Permalink
Browse files
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.
  • Loading branch information
aherbert committed Mar 20, 2022
1 parent d16d614 commit 2ffe262e5c4504b9f16bb9bf94fbbe195da394ab
Showing 4 changed files with 43 additions and 3 deletions.
@@ -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
@@ -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
@@ -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.
@@ -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>

0 comments on commit 2ffe262

Please sign in to comment.