CG: clarify regtest and regresssion searching.

diff --git a/Documentation/contributor/issues.itexi b/Documentation/contributor/issues.itexi
index 4260e838ad02b9339fde2bf594cca85bb6702fb5..7c715a4aedbd8df4d583a6c59b343cc8973af271 100644 (file)
--- a/Documentation/contributor/issues.itexi
+++ b/Documentation/contributor/issues.itexi
@@ -733,8 +733,9 @@ Git has special functionality to help tracking down the exact
 commit which causes a problem.  See the git manual page for
 @code{git bisect}.  This is a job that non-programmers can do,
 although it requires familiarity with git, ability to compile
 commit which causes a problem.  See the git manual page for
 @code{git bisect}.  This is a job that non-programmers can do,
 although it requires familiarity with git, ability to compile

-LilyPond, and generally a fair amount of technical knowledge.  An
-in-depth explanation of this process will not be given here.
+LilyPond, and generally a fair amount of technical knowledge.  A
+brief summary is given below, but you may need to consult other
+documentation for in-depth explanations.

 
 Even if you are not familiar with git or are not able to compile
 LilyPond you can still help to narrow down the cause of a
 
 Even if you are not familiar with git or are not able to compile
 LilyPond you can still help to narrow down the cause of a


@@ -742,7 +743,7 @@ regression simply by downloading the binary releases of different
 LilyPond versions and testing them for the regression.  Knowing
 which version of LilyPond first exhibited the regression is
 helpful to a developer as it shortens the @code{git bisect}
 LilyPond versions and testing them for the regression.  Knowing
 which version of LilyPond first exhibited the regression is
 helpful to a developer as it shortens the @code{git bisect}

-procedure described above.
+procedure.

 
 Once a problematic commit is identified, the programmers' job is
 much easier.  In fact, for most regression bugs, the majority of
 
 Once a problematic commit is identified, the programmers' job is
 much easier.  In fact, for most regression bugs, the majority of


@@ -750,3 +751,119 @@ the time is spent simply finding the problematic commit.
 
 More information is in @ref{Regression tests}.
 
 
 More information is in @ref{Regression tests}.
 

+@subheading git bisect setup
+
+We need to set up the bisect for each problem we want to
+investigate.
+
+Suppose we have an input file which compiled in version 2.13.32,
+but fails in version 2.13.38 and above.
+
+@enumerate
+@item
+Begin the process:
+
+@example
+git bisect start
+@end example
+
+@item
+Give it the earliest known bad tag:
+
+@example
+git bisect bad release/2.13.38-1
+@end example
+
+(you can see tags with: @code{git tag} )
+
+@item
+Give it the latest known good tag:
+
+@example
+git bisect good release/2.13.32-1
+@end example
+
+You should now see something like:
+@example
+Bisecting: 195 revisions left to test after this (roughly 8 steps)
+[b17e2f3d7a5853a30f7d5a3cdc6b5079e77a3d2a] Web: Announcement
+update for the new "LilyPond Report"
+@end example
+
+@end enumerate
+
+@subheading git bisect actual
+
+@enumerate
+
+@item
+Compile the source:
+
+@example
+make
+@end example
+
+@item
+Test your input file:
+
+@example
+out/bin/lilypond test.ly
+@end example
+
+@item
+Test results?
+
+@itemize
+@item
+Does it crash, or is the output bad?  If so:
+
+@example
+git bisect bad
+@end example
+
+@item
+Does your input file produce good output?  If so:
+
+@example
+git bisect good
+@end example
+
+@end itemize
+
+@item
+Once the exact problem commit has been identified, git will inform
+you with a message like:
+
+@example
+6d28aebbaaab1be9961a00bf15a1ef93acb91e30 is the first bad commit
+%%% ... blah blah blah ...
+@end example
+
+If there is still a range of commits, then git will automatically
+select a new version for you to test.  Go to step #1.
+
+@end enumerate
+
+@subheading Recommendation: use two terminal windows
+
+@itemize
+@item
+One window is open to the @code{build/} directory, and alternates
+between these commands:
+
+@example
+make
+out/bin/lilypond test.ly
+@end example
+
+@item
+One window is open to the top source directory, and alternates
+between these commands:
+
+@example
+git bisect good
+git bisect bad
+@end example
+
+@end itemize
+

diff --git a/Documentation/contributor/regressions.itexi b/Documentation/contributor/regressions.itexi
index 28debc1cdeea98c4170f3c3864d05f6d6c640dca..2695f1cfc92c3a76c474de713b811bc3b8738d71 100644 (file)
--- a/Documentation/contributor/regressions.itexi
+++ b/Documentation/contributor/regressions.itexi
@@ -195,6 +195,9 @@ make test-baseline
 @item
 Make your changes, or apply the patch(es) to consider.
 
 @item
 Make your changes, or apply the patch(es) to consider.
 

+@item
+Compile the source with @samp{make} as usual.
+

 @item
 Check for unintentional changes to the regtests:
 
 @item
 Check for unintentional changes to the regtests:
 


@@ -226,6 +229,9 @@ If you are happy with the results, then stop now.
 If you want to continue programming, then make any additional code
 changes, and continue.
 
 If you want to continue programming, then make any additional code
 changes, and continue.
 

+@item
+Compile the source with @samp{make} as usual.
+

 @item
 To re-check files that differed between the initial
 @samp{make@tie{}test-baseline} and your post-changes
 @item
 To re-check files that differed between the initial
 @samp{make@tie{}test-baseline} and your post-changes