Web: add regtest checking to helpus, final touches

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

diff --git a/Documentation/contributor/regressions.itexi b/Documentation/contributor/regressions.itexi
index 6cd15b59ca8ff3d5513cc1da6ef4748da3c2bc33..a5dac4822651ec72a8b5611a71d031d907747199 100644 (file)
--- a/Documentation/contributor/regressions.itexi
+++ b/Documentation/contributor/regressions.itexi
@@ -10,6 +10,7 @@
 * Finding the cause of a regression::
 * Memory and coverage tests::
 * MusicXML tests::
+* Grand Regression Test Checking::
 @end menu
 
 
@@ -155,7 +156,7 @@ make test
 @end example
 
 If you have a multi-core machine you may want to use the @option{-j}
-option and @var{CPU_COUT} variable, as
+option and @var{CPU_COUNT} variable, as
 described in @ref{Saving time with CPU_COUNT}.
 For a quad-core processor the complete command would be:
 
@@ -222,7 +223,7 @@ out/test-results/index.html
 @end example
 
 For each regression test that differs between the baseline and the
-changed code, a regression test entry will displayed.  Ideally,
+changed code, a regression test entry will be displayed.  Ideally,
 the only changes would be the changes that you were working on.
 If regressions are introduced, they must be fixed before
 committing the code.
@@ -463,10 +464,56 @@ The MusicXML regression tests are found at
 @file{input/regression/musicxml/}.
 
 The output resulting from running these tests
-through @samp{muscxml2ly} followed by @samp{lilypond} is
+through @samp{musicxml2ly} followed by @samp{lilypond} is
 available in the LilyPond documentation:
 
 @example
 @uref{http://lilypond.org/doc/latest/input/regression/musicxml/collated-files}
 @end example
 
+
+@node Grand Regression Test Checking
+@section Grand Regression Test Checking
+
+@subheading What is this all about?
+
+Regression tests (usually abbreviated "regtests") is a collection
+of @file{.ly} files used to check whether LilyPond is working correctly.
+Example: before version 2.15.12 breve noteheads had incorrect width,
+which resulted in collisions with other objects.  After the issue was fixed,
+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.
+
+@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:
+
+@example
+@uref{http://www.philholmes.net/lilypond/regtests/}
+@end example
+
+@subheading Some tips on checking regtests
+
+@subsubheading Description text
+
+The description should be clear even for a music beginner.
+If there are any special terms used in the description,
+they all should be explained in our @rglosnamed{Top, Music Glossary}
+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
+straightforward: it should be obvious what it checks and how.  Also, it
+usually shouldn't check everything at once.  For example it's a bad idea to test
+accidental placement by constucting one huge chord with many suspended notes
+and loads of accidentals.  It's better to divide such problem into a series
+of clearly separated cases.
+@end ignore