[PATCH] testbot: Update the Job, Step and Task documentation.

[Francois Gouget]

Signed-off-by: Francois Gouget <fgouget(a)codeweavers.com>
---
 testbot/lib/WineTestBot/Jobs.pm  | 24 ++++++++++++++++++++---
 testbot/lib/WineTestBot/Steps.pm | 33 +++++++++++++++++++++++++++++---
 testbot/lib/WineTestBot/Tasks.pm | 31 ++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/testbot/lib/WineTestBot/Jobs.pm b/testbot/lib/WineTestBot/Jobs.pm
index ef0d98e24..b1ffd3e48 100644
--- a/testbot/lib/WineTestBot/Jobs.pm
+++ b/testbot/lib/WineTestBot/Jobs.pm
@@ -28,13 +28,14 @@ WineTestBot::Job - A job submitted by a user
 =head1 DESCRIPTION
 
 A Job is created when a WineTestBot::User asks for something to be tested
-(for automatically generated Jobs this would be the batch user). There are many
+(for automatically generated Jobs this would be the batch user). A Job is
+composed of one or more WineTestBot::Step objects. There are many
 paths that can result in the creation of a job:
 
 =over
 
 =item *
-A use submits a patch or binary to test.
+A user submits a patch or binary to test.
 
 =item *
 WineTestBot finds a patch to test on the mailing list (and has all the pieces
@@ -47,7 +48,24 @@ Job.
 
 =back
 
-A Job is composed of multiple WineTestBot::Step objects.
+A Job's lifecycle is as follows:
+=over
+
+=item *
+A Job is created with Status set to queued which means it is ready to run.
+
+=item *
+As soon as one of the Step starts running, the Job's Status field is set to
+running.
+
+=item *
+Once all the Steps have completed the Job's Status is updated to reflect the
+overall result: completed, badpatch, etc.
+
+=item *
+If the Job is canceled by the user, then the Status field is set to canceled.
+
+=back
 
 =cut
 
diff --git a/testbot/lib/WineTestBot/Steps.pm b/testbot/lib/WineTestBot/Steps.pm
index 635092d1a..4dc45690e 100644
--- a/testbot/lib/WineTestBot/Steps.pm
+++ b/testbot/lib/WineTestBot/Steps.pm
@@ -26,9 +26,36 @@ WineTestBot::Step - A Job's Step
 
 =head1 DESCRIPTION
 
-A Job is composed of multiple Steps that each do a specific operation: build
-the test executable, or run a given test, etc. A Step is in turn composed of
-a WineTestBot::Task object for each VM it should be run on.
+A Job is composed of one or more Steps that each perform one operation. A
+Step is in turn composed of one WineTestBot::Task object for each VM that the
+Step should be run on.
+
+A Step's lifecyle is as follows:
+=over
+
+=item *
+A Step is created with Status set to queued which means it is ready to be run
+as soon as the PreviousNo Step has completed, or immediately if PreviousNo is
+not set.
+
+=item *
+Once one of the Step's Task is running the Step's Status is changed to
+running.
+
+=item *
+Once all the Tasks in the Step have completed, the Step's Status is set to one
+of the "completion" Status values according to the overall success of its
+Tasks: completed, badpatch, etc.
+
+=item *
+If the PreviousNo Step failed then the Status field and that of all its Tasks
+is set to skip; and the Step will not be run.
+
+=item *
+If a Step is canceled by the user, then the Status field is set to canceled if
+the Step was running, and to skipped if it was queued.
+
+=back
 
 Note that the PreviousNo relation will prevent the deletion of the target Step.
 It is the responsibility of the caller to delete the Steps in a suitable order,
diff --git a/testbot/lib/WineTestBot/Tasks.pm b/testbot/lib/WineTestBot/Tasks.pm
index 69d551b84..afd4fb4d3 100644
--- a/testbot/lib/WineTestBot/Tasks.pm
+++ b/testbot/lib/WineTestBot/Tasks.pm
@@ -31,6 +31,37 @@ performing that Step in a WineTestBot::VM virtual machine. For instance a Step
 responsible for running a given test would have one Task object for each
 virtual machine that the test must be performed in.
 
+A Task's lifecyle is as follows:
+=over
+
+=item *
+A Task is created with Status set to queued which means it is ready to be run
+as soon as long as the Step itself is runnable (see the WineTestBot::Step
+documentation).
+
+=item *
+Once the Task is running on the corresponding VM the Status field is set to
+running.
+
+=item *
+If running the Task fails due to a transient error the TestFailure field
+is checked. If it is lower than a configurable threshold the Status is
+reset to queued and the TestFailure field is incremented. Otherwise the
+Status is set to boterror and the Task is considered to have completed.
+
+=item *
+If the Task completes normally the Status field is set to the appropriate
+value based on the result: completed, badpatch, etc.
+
+=item *
+If the Task is canceled by the user its Status is set to canceled.
+
+=item *
+If the Task's Step cannot be run because the Step it depends on failed, then
+Status is set to skipped.
+
+=back
+
 =cut
 
 use WineTestBot::WineTestBotObjects;
-- 
2.17.0