Skip to content

Commit

Permalink
Always refer to "finally" tasks 📖
Browse files Browse the repository at this point in the history 
This commit changes all references to "final tasks" to "finally tasks".
We were using a mix of "final tasks" and "finally tasks" to refer to
these tasks, so this commit is making us consistently use one version.
However "finally tasks" is less grammatically correct that "final tasks"
because finally is an adverb - "finally tasks" only makes sense if
"finally tasks" is considered short for "finally tasks in a pipeline".
Another option sould be to go the other way and always use "final tasks"
(and never say "finally tasks"). However if we do this, @Srivaralakshmi
pointed out in #4086 that
this may make it confusing in that reading something like 'the final tasks'
may make a user expect to see a seciton in the pipeline called `final`
instead of the actual section `finally`.

We have another option which is to consider `finally`- an adverb - a
bad name for that section of the Pipeline spec and change it to `final`.
My understanding of the syntax is a bit different, e.g.:
```yaml
spec:
  tasks:
    - name: tests
      taskRef:
        name: integration-test
  finally:
    - name: cleanup-test
      taskRef:
        name: cleanup
```
I understand the finally section to be saying: once all of the above is
done, finally run clean-test, and not to say "cleanup-test is a finally
kind of task". However that would be a big change (tho pre-v1 would be
the time to do it!) and `finally` is consistent with how this kind of
functionality is expressed in languages like Python.

The last option would be to support both final and finally but that
feels to me like it would be even more confusing.
  • Loading branch information
@bobcatfish
bobcatfish committed Jul 12, 2021
1 parent 7e4189d commit 44a6ff9
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 40 deletions.
6 changes: 3 additions & 3 deletions docs/pipelineruns.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -562,7 +562,7 @@ Task Runs:

To cancel a `PipelineRun` that's currently executing, update its definition
to mark it as "PipelineRunCancelled". When you do so, the spawned `TaskRuns` are also marked
as cancelled and all associated `Pods` are deleted. Pending final tasks are not scheduled.
as cancelled and all associated `Pods` are deleted. Pending finally tasks are not scheduled.
For example:

```yaml
Expand All @@ -584,7 +584,7 @@ is currently an **_alpha feature_**.

To gracefully cancel a `PipelineRun` that's currently executing, update its definition
to mark it as "CancelledRunFinally". When you do so, the spawned `TaskRuns` are also marked
as cancelled and all associated `Pods` are deleted. Final tasks are scheduled normally.
as cancelled and all associated `Pods` are deleted. Finally tasks are scheduled normally.
For example:

```yaml
Expand All @@ -602,7 +602,7 @@ spec:

To gracefully stop a `PipelineRun` that's currently executing, update its definition
to mark it as "StoppedRunFinally". When you do so, the spawned `TaskRuns` are completed normally,
but no new non-final task is scheduled. Final tasks are executed afterwards.
but no new non-finally task is scheduled. Finally tasks are executed afterwards.
For example:

```yaml
Expand Down
74 changes: 37 additions & 37 deletions docs/pipelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ weight: 400
- [Configuring the `Task` execution order](#configuring-the-task-execution-order)
- [Adding a description](#adding-a-description)
- [Adding `Finally` to the `Pipeline`](#adding-finally-to-the-pipeline)
- [Specifying `Workspaces` in Final Tasks](#specifying-workspaces-in-final-tasks)
- [Specifying `Parameters` in Final Tasks](#specifying-parameters-in-final-tasks)
- [Specifying `Workspaces` in Finally Tasks](#specifying-workspaces-in-finally-tasks)
- [Specifying `Parameters` in Finally Tasks](#specifying-parameters-in-finally-tasks)
- [Consuming `Task` execution results in `finally`](#consuming-task-execution-results-in-finally)
- [`PipelineRun` Status with `finally`](#pipelinerun-status-with-finally)
- [Using Execution `Status` of `pipelineTask`](#using-execution-status-of-pipelinetask)
Expand All @@ -39,9 +39,9 @@ weight: 400
- [`WhenExpressions` using `Execution Status` of `PipelineTask` in `Finally Tasks`](#whenexpressions-using-execution-status-of-pipelinetask-in-finally-tasks)
- [`WhenExpressions` using `Aggregate Execution Status` of `Tasks` in `Finally Tasks`](#whenexpressions-using-aggregate-execution-status-of-tasks-in-finally-tasks)
- [Known Limitations](#known-limitations)
- [Specifying `Resources` in Final Tasks](#specifying-resources-in-final-tasks)
- [Cannot configure the Final Task execution order](#cannot-configure-the-final-task-execution-order)
- [Cannot specify execution `Conditions` in Final Tasks](#cannot-specify-execution-conditions-in-final-tasks)
- [Specifying `Resources` in Finally Tasks](#specifying-resources-in-finally-tasks)
- [Cannot configure the Finally Task execution order](#cannot-configure-the-finally-task-execution-order)
- [Cannot specify execution `Conditions` in Finally Tasks](#cannot-specify-execution-conditions-in-finally-tasks)
- [Cannot configure `Pipeline` result with `finally`](#cannot-configure-pipeline-result-with-finally)
- [Using Custom Tasks](#using-custom-tasks)
- [Specifying the target Custom Task](#specifying-the-target-custom-task)
Expand Down Expand Up @@ -783,9 +783,9 @@ The `description` field is an optional field and can be used to provide descript

## Adding `Finally` to the `Pipeline`

You can specify a list of one or more final tasks under `finally` section. Final tasks are guaranteed to be executed
in parallel after all `PipelineTasks` under `tasks` have completed regardless of success or error. Final tasks are very
similar to `PipelineTasks` under `tasks` section and follow the same syntax. Each final task must have a
You can specify a list of one or more final tasks under `finally` section. Finally tasks are guaranteed to be executed
in parallel after all `PipelineTasks` under `tasks` have completed regardless of success or error. Finally tasks are very
similar to `PipelineTasks` under `tasks` section and follow the same syntax. Each finally task must have a
[valid](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) `name` and a [taskRef or
taskSpec](taskruns.md#specifying-the-target-task). For example:

Expand All @@ -801,11 +801,11 @@ spec:
name: cleanup
```

### Specifying `Workspaces` in Final Tasks
### Specifying `Workspaces` in Finally Tasks

Finally tasks can specify [workspaces](workspaces.md) which `PipelineTasks` might have utilized
e.g. a mount point for credentials held in Secrets. To support that requirement, you can specify one or more
`Workspaces` in the `workspaces` field for the final tasks similar to `tasks`.
`Workspaces` in the `workspaces` field for the finally tasks similar to `tasks`.

```yaml
spec:
Expand Down Expand Up @@ -834,9 +834,9 @@ spec:
workspace: shared-workspace
```

### Specifying `Parameters` in Final Tasks
### Specifying `Parameters` in Finally Tasks

Similar to `tasks`, you can specify [`Parameters`](tasks.md#specifying-parameters) in final tasks:
Similar to `tasks`, you can specify [`Parameters`](tasks.md#specifying-parameters) in finally tasks:

```yaml
spec:
Expand All @@ -855,7 +855,7 @@ spec:

### Consuming `Task` execution results in `finally`

Final tasks can be configured to consume `Results` of `PipelineTask` from the `tasks` section:
Finally tasks can be configured to consume `Results` of `PipelineTask` from the `tasks` section:

```yaml
spec:
Expand All @@ -869,19 +869,19 @@ spec:
- name: commit
value: $(tasks.clone-app-repo.results.commit)
```
**Note:** The scheduling of such final task does not change, it will still be executed in parallel with other
final tasks after all non-final tasks are done.
**Note:** The scheduling of such finally task does not change, it will still be executed in parallel with other
finally tasks after all non-finally tasks are done.

The controller resolves task results before executing the finally task `discover-git-commit`. If the task
`clone-app-repo` failed or skipped with [when expression](#guard-task-execution-using-whenexpressions) resulting in
uninitialized task result `commit`, the finally Task `discover-git-commit` will be included in the list of
`skippedTasks` and continues executing rest of the final tasks. The pipeline exits with `completion` instead of
`skippedTasks` and continues executing rest of the finally tasks. The pipeline exits with `completion` instead of
`success` if a finally task is added to the list of `skippedTasks`.


### `PipelineRun` Status with `finally`

With `finally`, `PipelineRun` status is calculated based on `PipelineTasks` under `tasks` section and final tasks.
With `finally`, `PipelineRun` status is calculated based on `PipelineTasks` under `tasks` section and finally tasks.

Without `finally`:

Expand All @@ -893,20 +893,20 @@ Without `finally`:

With `finally`:

| `PipelineTasks` under `tasks` | Final Tasks | `PipelineRun` status | Reason |
| `PipelineTasks` under `tasks` | Finally Tasks | `PipelineRun` status | Reason |
| ----------------------------- | ----------- | -------------------- | ------ |
| all `PipelineTask` successful | all final tasks successful | `true` | `Succeeded` |
| all `PipelineTask` successful | one or more failure of final tasks | `false` | `Failed` |
| one or more `PipelineTask` [skipped](conditions.md) and rest successful | all final tasks successful | `true` | `Completed` |
| one or more `PipelineTask` [skipped](conditions.md) and rest successful | one or more failure of final tasks | `false` | `Failed` |
| single failure of `PipelineTask` | all final tasks successful | `false` | `failed` |
| single failure of `PipelineTask` | one or more failure of final tasks | `false` | `failed` |
| all `PipelineTask` successful | all finally tasks successful | `true` | `Succeeded` |
| all `PipelineTask` successful | one or more failure of finally tasks | `false` | `Failed` |
| one or more `PipelineTask` [skipped](conditions.md) and rest successful | all finally tasks successful | `true` | `Completed` |
| one or more `PipelineTask` [skipped](conditions.md) and rest successful | one or more failure of finally tasks | `false` | `Failed` |
| single failure of `PipelineTask` | all finally tasks successful | `false` | `failed` |
| single failure of `PipelineTask` | one or more failure of finally tasks | `false` | `failed` |

Overall, `PipelineRun` state transitioning is explained below for respective scenarios:

* All `PipelineTask` and final tasks are successful: `Started` -> `Running` -> `Succeeded`
* All `PipelineTask` and finally tasks are successful: `Started` -> `Running` -> `Succeeded`
* At least one `PipelineTask` skipped and rest successful: `Started` -> `Running` -> `Completed`
* One `PipelineTask` failed / one or more final tasks failed: `Started` -> `Running` -> `Failed`
* One `PipelineTask` failed / one or more finally tasks failed: `Started` -> `Running` -> `Failed`

Please refer to the [table](pipelineruns.md#monitoring-execution-status) under Monitoring Execution Status to learn about
what kind of events are triggered based on the `Pipelinerun` status.
Expand Down Expand Up @@ -1113,11 +1113,11 @@ For an end-to-end example, see [PipelineRun with WhenExpressions](../examples/v1

### Known Limitations

#### Specifying `Resources` in Final Tasks
#### Specifying `Resources` in Finally Tasks

Similar to `tasks`, you can use [PipelineResources](#specifying-resources) as inputs and outputs for
final tasks in the Pipeline. The only difference here is, final tasks with an input resource can not have a `from` clause
like a `PipelineTask` from `tasks` section. For example:
finally tasks in the Pipeline. The only difference here is, final tasks with an input resource can not have a `from`
clause like a `PipelineTask` from `tasks` section. For example:

```yaml
spec:
Expand All @@ -1144,21 +1144,21 @@ spec:
- tests
```

#### Cannot configure the Final Task execution order
#### Cannot configure the Finally Task execution order

It's not possible to configure or modify the execution order of the final tasks. Unlike `Tasks` in a `Pipeline`,
all final tasks run simultaneously and start executing once all `PipelineTasks` under `tasks` have settled which means
no `runAfter` can be specified in final tasks.
It's not possible to configure or modify the execution order of the finally tasks. Unlike `Tasks` in a `Pipeline`,
all finally tasks run simultaneously and start executing once all `PipelineTasks` under `tasks` have settled which means
no `runAfter` can be specified in finally tasks.

#### Cannot specify execution `Conditions` in Final Tasks
#### Cannot specify execution `Conditions` in Finally Tasks

`Tasks` in a `Pipeline` can be configured to run only if some conditions are satisfied using `conditions`. But the
final tasks are guaranteed to be executed after all `PipelineTasks` therefore no `conditions` can be specified in
final tasks.
finally tasks are guaranteed to be executed after all `PipelineTasks` therefore no `conditions` can be specified in
finally tasks.

#### Cannot configure `Pipeline` result with `finally`

Final tasks can emit `Results` but results emitted from the final tasks can not be configured in the
Finally tasks can emit `Results` but results emitted from the finally tasks can not be configured in the
[Pipeline Results](#configuring-execution-results-at-the-pipeline-level). We are working on adding support for this
(tracked in issue [#2710](https://github.com/tektoncd/pipeline/issues/2710)).

Expand Down

0 comments on commit 44a6ff9

Please sign in to comment.