Merge lp:~joetalbott/utah/doc_client_updates into lp:utah

[Joe Talbott]

Add some wording to clarify which fields in the control and runlist files are required.

[Max Brustkern (nuclearbob)]

On line 31 of the merge:
'Name' must correspond tot the
I'm guessing you mean "to the".

On line 42:
has cachedd credentials
Maybe "cached"?

Finally, when tc_setup sets up the "environment" this doesn't appear to include any propagating environment variables defined in tc_setup into the environment used to run the actual command. I'm guessing this is intentional, but it might be useful to note that in here somewhere? I'm not sure of the best way to put it.

Other than that, good stuff.

[lp:~joetalbott/utah/doc_client_updates]

689. By Joe Talbott on 2012-09-28

client - Fix some typos and reword 'tc_setup' description.

[Joe Talbott (joetalbott)]

Updated to address the issues you pointed out.

review: Needs Resubmitting

[Max Brustkern (nuclearbob)]

Looks good.

review: Approve

=== modified file 'debian/changelog'
--- debian/changelog	2012-09-27 13:57:33 +0000
+++ debian/changelog	2012-09-28 20:19:20 +0000
@@ -1,3 +1,9 @@
+utah (0.4ubuntu67) precise; urgency=low
+
+  * Update client docs to explain files a bit more clearly
+
+ -- Joe Talbott <[e-mail]>  Thu, 27 Sep 2012 12:50:08 -0400
+
 utah (0.4ubuntu66) precise; urgency=low
 
   * Add 'run_as' support

=== modified file 'docs/source/development.rst'
--- docs/source/development.rst	2012-09-27 14:37:27 +0000
+++ docs/source/development.rst	2012-09-28 20:19:20 +0000
@@ -64,7 +64,7 @@
 
     - name: testsuite1
       fetch_cmd : git clone/pull wherever
-        include_tests:
+      include_tests:
         - t1
         - t2
         - t3...
@@ -74,6 +74,10 @@
         - st4
         - st5
 
+The only required fields are 'name' and 'fetch_cmd'.  'Name' must correspond to the name of the top-level testsuite directory.  'Fetch_cmd' should be a command that populates the testsuite directory created by utah-client with actual testsuite directory structure.
+
+'Include_tests' will limit the testcases that are run to only those listed by this option.  'Exclude_tests' will run all the tests in the testsuite's tslist.run file except those listed by this option.
+
 Test suites can be divided in categories (for our internal use, or for test
 cases submitted to our test case base) or they can be in a repository anywhere.
 
@@ -91,6 +95,8 @@
       overrides:                           # array of control properties to override
       - timeout: 200                       # timeout in seconds
 
+'Test' is the only required field in this file and must match a directory name in the testsuite tree.  'Run_as' utilizes sudo to run the testcase as the given user. NOTE: this requires that the user running the utah client either has cached credentials or is allowed to run commands without a password.  The 'overrides' array accepts any option from the tc_control file.  Overrides should be used sparingly since it makes more sense to adjust the options in the tc_control file rather than here.
+
 **ts_control file contains:**
 
 ::
@@ -101,6 +107,7 @@
                                          # the whole test suite
     ts_cleanup:     tcleanup/cleanup.sh  # clean up test suite
 
+There are no required fields in this file.
 
 To avoid excessive typing and repetition in runlists and control files the
 following rules apply:
@@ -147,6 +154,12 @@
     tc_setup:       t1/t1 setup    # in case the test case has a setup
     tc_cleanup:     t1/t1 cleanup  # in case the test has a cleanup
 
+In this file 'command', 'description', 'dependencies', 'actions', 'expected_results', and 'timeout' are required.  'Command' is the command to actually run the test.  'Description' is a textual description of the test.  'Dependencies' is a list of items the test depends on.  'Action' is a list of actions the test executes and 'expected_results' is a list of what those actions should result in.  'Timeout' is the ammount of time the test should complete within and is used to avoid tests that might loop indefinitely.
+
+'Type' currently defaults to 'userland' and may in the future have other options as the need arises.
+
+'Build_cmd' can be used to build any binary test cases.  'Tc_setup' can be used to setup any needed data or files for the test and 'tc_cleanup' can be used to remove the data or files added by 'tc_setup'.  'Build_cmd', 'tc_setup', and 'tc_cleanup' are all simple shell commands similar to 'command'.
+
 For each test case that is a binary or a script, there will be an option
 to define a setup and a cleanup function if they wish so, and it is the test
 code developer’s responsibility to add the right parameters to their code so