CG: describe new C++ formatting (GOP-PROP 3)

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

diff --git a/Documentation/contributor/regressions.itexi b/Documentation/contributor/regressions.itexi
index e2216f1a0bbc9c0052f30d80726882c9a4d91006..7f4c9276169c22f9f52462b9fa95ee595df245c1 100644 (file)
--- a/Documentation/contributor/regressions.itexi
+++ b/Documentation/contributor/regressions.itexi
@@ -22,9 +22,11 @@ These regression tests comprise small LilyPond snippets that test
 the functionality of each part of LilyPond.
 
 Regression tests are added when new functionality is added to
-LilyPond.  They are also added when bugs are identified.  The
-snippet that causes the bug becomes a regression test to verify
-that the bug has been fixed.
+LilyPond.
+We do not yet have a policy on when it is appropriate to add or
+modify a regtest when bugs are fixed.  Individual developers
+should use their best judgement until this is clarified during the
+@ref{Grand Organization Project (GOP)}.
 
 The regression tests are compiled using special @code{make}
 targets.  There are three primary uses for the regression
@@ -186,8 +188,11 @@ twice.
 @enumerate
 
 @item
-Before making changes, a baseline should be established by
-running:
+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:
 
 @example
 make test-baseline
@@ -207,7 +212,7 @@ make check
 @end example
 
 After this has finished, a regression test comparison will be
-available at:
+available (relative to the current @file{build/} directory) at:
 
 @example
 out/test-results/index.html
@@ -262,6 +267,15 @@ automatic regression comparison again.
 
 @end enumerate
 
+@advanced{
+Once a test baseline has been established, there is no need to run it again
+unless git master changed. In other words, if you work with several branches
+and want to do regtests comparison for all of them, you can
+@code{make test-baseline} with git master, checkout some branch,
+@code{make} and @code{make check} it, then switch to another branch,
+@code{make test-clean}, @code{make} and @code{make check} it without doing
+@code{make test-baseline} again.}
+
 
 @node Finding the cause of a regression
 @section Finding the cause of a regression
@@ -416,7 +430,9 @@ code has been exercised by the tests.
 
 For tracking memory usage as part of this test, you will need
 GUILE CVS; especially the following patch:
+@smallexample
 @uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
+@end smallexample
 
 @subheading Code coverage