From 27655d702bcb62e49566599c9b42f02917ab524a Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinkle@fastmail.com>
Date: Sat, 7 Dec 2024 16:19:31 +0000
Subject: [PATCH] Docs: Write "Changelog" section for QUnit.config.seed

---
 History.md                 |  6 +++---
 bin/qunit.js               |  2 +-
 docs/api/config/reorder.md |  4 ++++
 docs/api/config/seed.md    | 16 ++++++++++++----
 docs/cli.md                |  3 ++-
 5 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/History.md b/History.md
index a592f92f8..063eed1da 100644
--- a/History.md
+++ b/History.md
@@ -63,8 +63,8 @@ QUnit 3.0 Roadmap and feedback: https://github.com/qunitjs/qunit/issues/1498
 
 ### Fixed
 
-* CLI: Fix support for strict TAP parsers by limiting colors to test names. [#1801](https://github.com/qunitjs/qunit/pull/1801)
-* CLI: Fix confusing `--seed` eating the file argument. [#1691](https://github.com/qunitjs/qunit/issues/1691)
+* CLI: Fix support for strict [TAP parsers](https://qunitjs.com/api/config/reporters/#tap) by limiting colors to test names. [#1801](https://github.com/qunitjs/qunit/pull/1801)
+* CLI: Fix confusing [`--seed` option](https://qunitjs.com/api/config/seed/) eating the file argument. [#1691](https://github.com/qunitjs/qunit/issues/1691)
 * CLI: Remove confusing `expected: undefined` under error messages in TAP reporter. [#1794](https://github.com/qunitjs/qunit/pull/1794)
 * HTML Reporter: Fix broken "Rerun without max depth" link. [da0c59e101](https://github.com/qunitjs/qunit/commit/da0c59e1016685ecd2b813bba914d33170e7bf98) (see also [91db92dbc5](https://github.com/qunitjs/qunit/commit/91db92dbc50bbbc41c5060a27e7aafd4e073e289), [73c03cf277](https://github.com/qunitjs/qunit/commit/73c03cf27745e179396a6d7c9af011a20d3b9082))
 * HTML Reporter: Fix `<label>` to wrap `<select>` for multi-value urlConfig item. [#1773](https://github.com/qunitjs/qunit/pull/1773)
@@ -741,7 +741,7 @@ QUnit 3.0 Roadmap and feedback: https://github.com/qunitjs/qunit/issues/1498
 * Core: Reintroduce `QUnit.config.module`.
 * Core: Stop splitting URL parameter values by commas.
 * Core: New `moduleId`-based filtering.
-* Core: Support running tests in pseudo-random order.
+* Core: Introduce `QUnit.config.seed` for running tests in pseudo-random order.
 * Dump: Fix asymmetrical function dump argument spacing.
 * HTML Reporter: Fix escaping of diffs.
 * HTML Reporter: Add message explaining missing diff.
diff --git a/bin/qunit.js b/bin/qunit.js
index d1a01145c..9fe5a3074 100755
--- a/bin/qunit.js
+++ b/bin/qunit.js
@@ -38,7 +38,7 @@ program
   )
   .option('--seed <value>',
     'specify a seed to enable randomized ordering of tests.\n'
-    + 'set to "true" to generate a new seed.'
+    + 'set to "true" to generate a new random seed.'
   )
   .option('-w, --watch', 'watch files for changes and re-run the test suite')
   .parse(process.argv);
diff --git a/docs/api/config/reorder.md b/docs/api/config/reorder.md
index 64cd69242..23804d6a9 100644
--- a/docs/api/config/reorder.md
+++ b/docs/api/config/reorder.md
@@ -29,3 +29,7 @@ Note that this feature may lead to unexpected failures if you have non-atomic te
 This feature is limited to [browser environments](../../browser.md) by default, as it utilizes the `sessionStorage` API. Set [QUnit.config.storage](./storage.md) to enable this feature in Node.js or in other environments.
 
 The QUnit reorder feature was inspired by Kent Beck, who designed a similar mechanism in JUnit Max for Eclipse. <sup>[[1]](https://topenddevs.com/podcasts/javascript-jabber/episodes/050-jsj-qunit-with-jorn-zaefferer) [[2]](https://www.youtube.com/watch?v=g9ykvSI0gjg) [[3]](https://web.archive.org/web/20141018095913/http://junitmax.com/)</sup>
+
+## See also
+
+* [QUnit.config.seed](./seed.md)
diff --git a/docs/api/config/seed.md b/docs/api/config/seed.md
index f0cdf2871..42ba3e10f 100644
--- a/docs/api/config/seed.md
+++ b/docs/api/config/seed.md
@@ -28,13 +28,21 @@ This option is also available as [CLI option](../../cli.md), and as URL query pa
 
 </p>
 
-When set to boolean true, or a string, QUnit will run tests in a [seeded-random order](https://en.wikipedia.org/wiki/Random_seed).
-
-The provided string will be used as the seed in a pseudo-random number generator to ensure that results are reproducible. The randomization will also respect the [reorder](./reorder.md) option if enabled and re-run failed tests first without randomizing them.
+When enabled QUnit will run tests in a [seeded-random order](https://en.wikipedia.org/wiki/Random_seed).
 
 Randomly ordering your tests can help identify non-atomic tests which either depend on a previous test or are leaking state to subsequent tests.
 
-If `seed` is boolean true (or set as URL query parameter without a value), then QUnit will generate on-demand a new random value to use as seed. You can then read the seed from `QUnit.config.seed` at runtime, and use it to reproduce the same test sequence later.
+The provided string will be used as the seed in a pseudo-random number generator to ensure that results are reproducible. The randomization will respect the [reorder](./reorder.md) option if enabled, such that previously failed tests still run first instead of being shuffled.
+
+If `seed` is set to `true` (or add `?seed` to the URL, without any value), then QUnit will generate a new random seed every time you run the tests. To reproduce a specific random sequence, access the seed from `QUnit.config.seed` via the console.
+
+## Changelog
+
+| [QUnit 2.23.1](https://github.com/qunitjs/qunit/releases/tag/2.23.1) | Add support for CLI `--seed=true`, URL `?seed=true`, and [flat preconfig](./index.md#preconfiguration) `qunit_config_seed=true`.
+| [QUnit 2.21.0](https://github.com/qunitjs/qunit/releases/tag/2.21.0) | Introduce [flat preconfig](./index.md#preconfiguration), including `qunit_config_seed=<value>`.
+| [QUnit 2.3.0](https://github.com/qunitjs/qunit/releases/tag/2.3.0) | Introduce [QUnit CLI](../../cli.md), including `--seed <value>`.
+| [QUnit 2.1.0](https://github.com/qunitjs/qunit/releases/tag/2.1.0) | Introduce [object preconfig](./index.md#preconfiguration), including `QUnit.config.seed = true`.
+| [QUnit 1.23.0](https://github.com/qunitjs/qunit/releases/tag/1.23.0) | Introduce `QUnit.config.seed`, with `?seed` as way to generate a new random seed.
 
 ## See also
 
diff --git a/docs/cli.md b/docs/cli.md
index c607a5589..d130ee612 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -104,7 +104,8 @@ Options:
   -m, --module <name>    run only the specified module
   -r, --reporter [name]  specify the reporter to use
   --require <module>     specify a module or script to include before running any tests
-  --seed [value]         specify a seed to re-order your tests
+  --seed <value>         specify a seed to enable randomized ordering of tests.
+                         set to "true" to generate a new random seed.
   -w, --watch            watch files for changes and re-run the test suite
   -h, --help             display help for command
 ```