Website: Documenting descriptions for Job and Task Statuses in the documentation webpage. #104214

Merged
Sybren A. Stüvel merged 5 commits from Adi.Sage/flamenco:updating-job-and-task-statuses into main 2023-06-22 19:41:53 +02:00

View File

@ -5,6 +5,25 @@ weight: 5
TODO: write about the pipeline from job submission to command execution.
## Job Statuses
The following table shows the meaning of the different job statuses:
| Status | Meaning | Possible next status |
| ------------------------- | ------- | ----------- |
| `under-construction` | Preparing job for execution | `queued`, `active` |
| `queued` | Ready to be assigned to available Workers | `active`, `canceled` |
| `active` | Tasks assigned to Workers for execution | `completed`, `canceled`, `failed` |
| `completed` | All tasks executed successfully | `queued` |
| `failed` | Execution of one or more tasks failed after multiple retries by different Workers | `queued`, `canceled` |
| `cancel-requested` | Request for job cancellation raised by user | `canceled` |
| `canceled` | Canceled by the user, job terminated immediately on all Workers | `queued` |
| `requeueing` | Request for requeueing of job raised by user | `queued` |
| `paused` | Not yet implemented | |
NOTE :
- Requeueing a job when it is `completed`, i.e. when all its tasks are `completed`, will requeue all its tasks.
- Requeueing a job when some of its tasks are not `completed` will requeue these tasks only. The `completed` tasks will not be requeued, and will remain at `completed` status.
## Task Statuses
@ -12,8 +31,10 @@ The following table shows the meaning of the different task statuses:
| Status | Meaning | Possible next status |
| ------------- | ------- | ----------- |
| `queued` | Ready to be worked on by a Worker | `active`, `canceled` |
| `active` | Assigned to a worker for execution | `completed`, `canceled`, `failed`, `soft-failed` |
| `soft-failed` | Same as `queued`, but has been failed by a worker in an earlier execution | `completed`, `failed`, `canceled` |
| `completed` | Worker executed the task succesfully | `requeued` |
| `queued` | Ready to be assigned to an available Worker | `active`, `canceled` |
| `active` | Assigned to a Worker for execution | `completed`, `canceled`, `failed`, `soft-failed` |

Another possible next status would be queued, as you can re-queue a job that has a mixture of task statuses, and after requeueing those should all go to either queued or remain at completed.

FYI: requeuing a job that's completed will requeue all its tasks. When that the job was not 100% complete yet, it will only requeue the not-yet-completed tasks, and leave the completed ones alone.

Another possible next status would be `queued`, as you can re-queue a job that has a mixture of task statuses, and after requeueing those should all go to either `queued` or remain at `completed`. FYI: requeuing a job that's `completed` will requeue all its tasks. When that the job was not 100% complete yet, it will only requeue the not-yet-completed tasks, and leave the completed ones alone.
Review

Noted 👍 I will remove the archive and archived as requested.

Can you elaborate on the following from your second comment :

  • Should I add 'queued' as a possible next status to all the status you have marked out?
  • And the 'FYI' part is just for me or should I add that as a description of 'completed' / 'active'?
Noted 👍 I will remove the `archive `and `archived` as requested. Can you elaborate on the following from your second comment : - Should I add 'queued' as a possible next status to all the status you have marked out? - And the 'FYI' part is just for me or should I add that as a description of 'completed' / 'active'?

Should I add 'queued' as a possible next status to all the status you have marked out?

It's not so clear here what I was referring to (compared to the old Phabricator-based review tool we used), my remark was purely about the soft-failed status.

And the 'FYI' part is just for me
It was intended just for you, but to be fair I do think it's a good idea if this makes it into the documentation somehow. Not sure if it looks good when added to this table, or whether it's better to write it down below that. I'll leave that choice to you. Also it could just be another PR later, if you want. Whatever is easiest for you.

> Should I add 'queued' as a possible next status to all the status you have marked out? It's not so clear here what I was referring to (compared to the old Phabricator-based review tool we used), my remark was purely about the `soft-failed` status. > And the 'FYI' part is just for me It was intended just for you, but to be fair I do think it's a good idea if this makes it into the documentation somehow. Not sure if it looks good when added to this table, or whether it's better to write it down below that. I'll leave that choice to you. Also it could just be another PR later, if you want. Whatever is easiest for you.
| `completed` | Task executed succesfully | `queued` |
| `soft-failed` | Same as `queued`, but has been failed by a Worker in an earlier execution | `queued`, `completed`, `failed`, `canceled` |
| `failed` | Execution failed after multiple retries by different Workers | `queued`, `canceled` |
| `canceled` | Canceled by the user, task terminated immediately | `queued` |
| `paused` | Not yet implemented | |