Add test-suite instructions.

[super-star-trek.git] / doc / HACKING

diff --git a/doc/HACKING b/doc/HACKING
index 5f03ced08ec47205a6edc92a09dc316266f208bd..4bf7b496c5592d1a91fe0a566e321cf72bd8ee07 100644 (file)
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -1,7 +1,7 @@
 This is the hackers' guide to SST2K.  Read it before messing with the code.
 
 It consists of an introduction, a history, suggestions for regression testing,
-some notes on the Python translation.  For a to-do list, see TODO in the
+and some notes on the Python translation.  For a to-do list, see TODO in the
 top-level directory.
 
 INTRODUCTION:
@@ -191,7 +191,7 @@ probability of being damaged."
 This is one place where OPTION_PLAIN does not restore the original
 behavior, which was equiprobable damage across all devices.  If we
 wanted that, we'd return randrange(NDEVICES) and have done with it.
-Also, in the original game, DNAVYS and DCOMPTR were the same device.
+Also, in the original game, DNAVSYS and DCOMPTR were the same device.
 
 Instead, we use a table of weights similar to the one from BSD Trek.
 BSD doesn't have the shuttle, shield controller, death ray, or probes.
@@ -216,21 +216,27 @@ This code has been designed to be tested.  A simple shellscript
 included in the distribution, 'replay', automatically reruns the
 last game you played.
 
-Here are some interesting seeds for debugging and regression testing
-For each one, I list the seed, the options, and the last svn revision
-for which it is known to have given the described behavior.
+See the "test" directory for regression-test logs and checkfiles.
+Please run 'make check' every time you change this game to be sure
+you haven't broken anything.  
 
-1160647745 regular short good fancy    (r769)
+When you fix a bug, add the log of the game that triggered it (and
+a checkfile) to the regression tests. This is how we improve the code
+coverage of the suite. 
 
-Starts you in a quadrant with the Super-Commander in it.  Slamming three
-torps at him will kill him.  You can use this to regression-test both
-torpedo tracks and the Deep Space Probe. Known bug: "probe aut 2 8"
-triggers manual navigation.
+Two things to do to the log before dropping it in the test directory:
 
-1160707235 regular short good fancy    (r769)
+(a) Strip out all lines beginning with "#curses:" - these are for debugging
+the curses interface and are not needed or regression testing; removing
+them makes it easier to see the game commands.
 
-Do sr/mov aut 5 4/sr/sensors/orbit/transport; you'll get a transporter
-failure.
+(b) Add a header comment line explaining what the log is a test for.
+It should begin with "# Tests". This is what gets echoed before each
+regression test is run.
+
+Then drop it into the test directory and "make buildregress" to create
+the check file. (Don't forget to commit and push the log and checkfile
+to the repository.)
 
 NOTES ON THE PYTHON TRANSLATION:
 
@@ -240,8 +246,8 @@ separate project).  I then hand-tuned and refactored the result.
 
 The LOC count dropped by almost exactly 20% during this process, from
 a bit over 8100 lines to a bit over 6500 lines.  If the code is still
-shorter than that when you read thism, it's because this file comtains
-nost of what used to be a huge header comment.  
+shorter than that when you read this, it's because this file contains
+most of what used to be a huge header comment.  
 
 SST is not a data-structure- intensive program, so it compresses less
 under translation to Python than the 50% drop in LOC I've found to be