From: Valentin Villenave <v.villenave@gmail.com>
Date: Thu, 27 May 2010 18:37:51 +0000 (+0200)
Subject: Doc: add stuff to CG "Regtests"
X-Git-Tag: release/2.13.23-1~29^2~16
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a0c4db575e6ae6cb4a6716800373834f1e0f4959;p=lilypond.git

Doc: add stuff to CG "Regtests"

This is clearly not ideal, but at least it's slightly
better than having empty sections. Hopefully someone
else will add more accurate/helpful information later.
---

diff --git a/Documentation/contributor/regressions.itexi b/Documentation/contributor/regressions.itexi
index a6106cea93..666172b167 100644
--- a/Documentation/contributor/regressions.itexi
+++ b/Documentation/contributor/regressions.itexi
@@ -49,9 +49,11 @@ technically involved.
 
 The easiest way to see the @q{current} regtest output (meaning,
 the ouput of the latest stable or development version) is
-to look at the precompiled regtest
-@uref{../../input/regression/collated-files.html, HTML page} or its
-@uref{../../input/regression/collated-files.pdf, pdf version}.
+to look at the online compiled regtest page:
+
+@example
+@uref{http://lilypond.org/doc/latest/input/regression/collated-files.html}
+@end example
 
 However, depending on how many changes have been made to the code
 since the latest release, this page may not reflect the latest
@@ -65,16 +67,19 @@ yourself, it is recommended that you compile the software yourself.
 
 The first step is to download the latest available source code,
 as explained in @ref{Working with source code}.  Then you will need
-to build the LilyPond binary@footnote{Uninstalling the previous
-LilyPond version is not necessary, nor is running @code{make install},
-since the tests will automatically be compiled with the LilyPond binary
-you have just built in your source directory.}: see
-@rcontrib{Compiling LilyPond}.
+to build the LilyPond binary: see
+@ref{Compiling LilyPond}.
+
+@noindent
+(Uninstalling the previous LilyPond version is not necessary, nor is
+running @code{make install}, since the tests will automatically be
+compiled with the LilyPond binary you have just built in your source
+directory.)
 
 From this point, compiling the regtests is as simple as running
 
 @example
-  make test
+make test
 @end example
 
 However, as there are many snippets to compile, if you have a multi-core
@@ -84,19 +89,66 @@ useful optimization is to set the @var{CPU_COUNT} variable; for a
 quad-core processor the complete command would look like
 
 @example
-  make -j5 CPU_COUNT=4 test
+make -j5 CPU_COUNT=4 test
 @end example
 
 The regtest output will then be available in one of the
 @file{input/regression/out-*} directories, depending on the
-exact command you used.
+exact command you used.  See @ref{Testing LilyPond} for
+more information.
 
 
 @node Comparison regtest output
 @section Comparison regtest output
 
 
+Regtests are an useful way to compare what has changed between two
+versions of LilyPond, or to verify on a fine-grained level if a
+particular change may have unwanted side-effects, such as introducing
+a bug or breaking existing features.
+
+For such cases, LilyPond's build system provides an automated way of
+comparing regtests output.
+
+
+@subheading Comparing regtests for two development releases
+
+Each time a new development version is released, a set of regtests is
+compiled and compared with the previous release.  The result of these
+comparisons is archived online, and may be seen at the following address:
+
+@example
+@uref{http://lilypond.org/test/}
+@end example
+
+@noindent
+Checking these pages is a very important task for the LilyPond project.  
+You are invited to report anything that looks broken, or any case
+where the output quality is not on par with the previous release,
+either to the Bug Squad, following our guidelines for
+@rweb{Bug reports}, or directly in the bug tracker, as explained in
+@ref{Issues}.
+
+
+@subheading Comparing regtests when modifying the source code
+
+When changing any piece of code, developers are asked to verify that the
+regtests still compile successfuly (i.e., not only without error, but
+with an output quality equivalent or superior).  This may be done as
+described in @ref{Testing LilyPond}.
+
+
 @node MusicXML tests
 @section MusicXML tests
 
 
+LilyPond comes with a fairly complete set of regtests for the
+@uref{http://www.musicxml.org/,MusicXML} language.  These tests may
+be seen online at the following address:
+
+@example
+@uref{http://lilypond.org/doc/latest/input/regression/musicxml/collated-files}
+@end example
+
+TBC
+