CG: note that CPU threads affect cell count in regtests (issue 3257)

[lilypond.git] / Documentation / contributor / regressions.itexi

diff --git a/Documentation/contributor/regressions.itexi b/Documentation/contributor/regressions.itexi
index 2c7783c1d7828e578c0ca940e24ecc6eab006264..8b600465f5ffbfda13c6b774b862846fab55d258 100644 (file)
--- a/Documentation/contributor/regressions.itexi
+++ b/Documentation/contributor/regressions.itexi
@@ -99,8 +99,20 @@ verify that the regression tests have, in fact, run.}
 
 The test comparison shows all of the changes that occurred between
 the current release and the prior release.  Each test that has a
-significant difference in output is displayed, with the old
-version on the left and the new version on the right.
+significant (noticeable) difference in output is displayed, with
+the old version on the left and the new version on the right.
+
+Some of the small changes can be ignored (slightly different slur
+shapes, small variations in note spacing), but this is not always
+the case: sometimes even the smallest change means that something
+is wrong.  To help in distinguishing these cases, we use bigger
+staff size when small differences matter.
+
+Staff size 30 generally means "pay extra attention to details".
+Staff size 40 (two times bigger than default size) or more means
+that the regtest @strong{is} about the details.
+
+Staff size smaller than default doesn't mean anything.
 
 Regression tests whose output is the same for both versions are
 not shown in the test comparison.
@@ -123,6 +135,11 @@ something is suspicious!
 @item
 Profile files: give information about
 TODO?  I don't know what they're for.
+Apparently they give some information about CPU usage.  If you got
+tons of changes in cell counts, this probably means that you compiled
+@code{make test-baseline} with a different amount of CPU threads than
+@code{make check}. Try redoing tests from scratch with the same
+number of threads each time -- see @ref{Saving time with the -j option}.
 
 @end itemize
 
@@ -183,7 +200,8 @@ than building the source code, as described in
 @node Regtest comparison
 @section Regtest comparison
 
-Before modified code is committed to master, a regression test
+Before modified code is committed to @code{master} (via @code{staging}),
+a regression test
 comparison must be completed to ensure that the changes have
 not caused problems with previously working code.  The comparison
 is made automatically upon compiling the regression test suite
@@ -196,7 +214,7 @@ Run @code{make} with current git master without any of your changes.
 
 @item
 Before making changes to the code, establish a baseline for the comparison by
-going to the @file{lilypond-git/build/} directory and running:
+going to the @file{$LILYPOND_GIT/build/} directory and running:
 
 @example
 make test-baseline
@@ -485,7 +503,9 @@ a small @file{.ly} file demonstrating the problem was added to the regression
 tests as a proof that the fix works.  If someone will accidentally break
 breve width again, we will notice this in the output of that regression test.
 
-We are asking you to help us by checking a regtest or two from time to time.
+@subheading How can I help?
+
+We ask you to help us by checking one or two regtests from time to time.
 You don't need programming skills to do this, not even LilyPond skills -
 just basic music notation knowledge; checking one regtest takes less than
 a minute.  Simply go here:
@@ -505,6 +525,7 @@ or @rinternalsnamed{Top, Internals Reference}.
 Vague descriptions (like "behaves well", "looks reasonable") shouldn't be used.
 
 @ignore
+this may be useful for advanced regtest checking
 @subsubheading Is regtest straightforward and systematic?
 
 Unfortunately some regtests are written poorly.  A good regtest should be