Module: tools Branch: master Commit: e35b3d03ed6d24f143fbe44fbef7344c87e0312a URL: https://source.winehq.org/git/tools.git/?a=commit;h=e35b3d03ed6d24f143fbe44f...
Author: Francois Gouget fgouget@codeweavers.com Date: Thu May 31 11:00:29 2018 +0200
testbot: Update the Job, Step and Task documentation.
Signed-off-by: Francois Gouget fgouget@codeweavers.com Signed-off-by: Alexandre Julliard julliard@winehq.org
---
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 ef0d98e..b1ffd3e 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 635092d..4dc4569 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 69d551b..afd4fb4 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;