[latex3-commits] [git/LaTeX3-latex3-l3build] regenerate: Add documentation (d54baa8)

[Marcel Fabian Krüger]

Repository : https://github.com/latex3/l3build
On branch  : regenerate
Link       : https://github.com/latex3/l3build/commit/d54baa805c5b783b2559e907ee2d14adf5c487dd

>---------------------------------------------------------------

commit d54baa805c5b783b2559e907ee2d14adf5c487dd
Author: Marcel Fabian Krüger <tex at 2krueger.de>
Date:   Wed May 26 19:47:46 2021 +0200

    Add documentation


>---------------------------------------------------------------

d54baa805c5b783b2559e907ee2d14adf5c487dd
 build.lua   |  1 +
 l3build.dtx | 26 ++++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/build.lua b/build.lua
index b88df70..990961f 100644
--- a/build.lua
+++ b/build.lua
@@ -16,6 +16,7 @@ packtdszip   = true
 scriptfiles  = {"l3build*.lua"}
 scriptmanfiles = {"l3build.1"}
 sourcefiles  = {"*.dtx", "l3build*.lua", "*.ins"}
+typesetruns  = 4
 typesetcmds  = "\\AtBeginDocument{\\DisableImplementation}"
 unpackdeps   = { }
 tagfiles     = {"l3build.1", "l3build.dtx", "*.md", "l3build.lua"}
diff --git a/l3build.dtx b/l3build.dtx
index fc1d1ed..fa7bbef 100644
--- a/l3build.dtx
+++ b/l3build.dtx
@@ -1119,6 +1119,32 @@
 %   \label{fig:test-tasks}
 % \end{figure}
 %
+% \subsection{Instructions for rebuilding test output}
+%
+% Sometimes changes to fundamental parts of the code can cause a lot of tests
+% to fail even though the actually tested systems are still working correctly.
+% This is especially common when the logging and error reporting systems
+% changes and therefore all log file based tests using the component fail with
+% these changes.
+%
+% In these cases, the option |--show-save-cmds| can be passed to
+% |l3build check| in order to generate a list of |l3build save| commands which
+% can be executed to regenerate the expected output of all tests which fail.
+% If engine specific tests are present, there can still be some test failures
+% after running these commands. In that case, running |l3build check| with
+% |--show-save-cmds| again followed by executing the generated list of
+% |l3build save| commands will regenerate the remaining tests. It is never
+% required to run this for a third time.
+%
+% This option is potentially dangerous and therefore should only be used with
+% care. It can easily hide valid test failures between a bunch of spurious
+% changes. Therefore you should always take a close look at the difference
+% files generated by |l3build check| before running the generated
+% |l3build save| commands. Additionally it should only be used when you are
+% aware of the reason why a large number of tests failed and the change
+% causing the failures has been tested separately to have no unintended
+% side effects.
+%
 % \subsection{Epoch setting}
 %
 % To produce predictable output when using dates, the test system offers the