[TEP-0047] add display name to pipeline spec and task spec

New fields are added to Pipeline, Task, and PipelineTask for display names, as well as a new field on PipelineTask for description. These "human readable" fields can be used to populate a UI in the future.
tektoncd · Mar 29, 2023 · 3d86fa5 · 3d86fa5
1 parent eae5c3a
commit 3d86fa5
Show file tree

Hide file tree

Showing 17 changed files with 548 additions and 4 deletions.
diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -533,6 +533,19 @@ PipelineSpec
 <table>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the pipeline that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -895,6 +908,19 @@ value.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the task that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -2490,6 +2516,19 @@ TaskRunStatus
 <tbody>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the pipeline that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -2606,6 +2645,32 @@ the execution order of tasks relative to one another.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is the display name of this task within the context of a Pipeline.
+This display name may be used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>description</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Description is the description of this task within the context of a Pipeline.
+This description may be used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>taskRef</code><br/>
 <em>
 <a href="#tekton.dev/v1.TaskRef">
@@ -5308,6 +5373,19 @@ value.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the task that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -6932,6 +7010,19 @@ value.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the task that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -7290,6 +7381,19 @@ PipelineSpec
 <table>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the pipeline that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -7679,6 +7783,19 @@ value.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the task that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -9695,6 +9812,19 @@ TaskRunStatus
 <tbody>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the pipeline that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string
@@ -9811,6 +9941,32 @@ the execution order of tasks relative to one another.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is the display name of this task within the context of a Pipeline.
+This display name may be used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>description</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Description is the description of this task within the context of a Pipeline.
+This description may be used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>taskRef</code><br/>
 <em>
 <a href="#tekton.dev/v1beta1.TaskRef">
@@ -12742,6 +12898,19 @@ value.</p>
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>DisplayName is a user-facing name of the task that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>description</code><br/>
 <em>
 string

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -94,6 +94,8 @@ A `Pipeline` definition supports the following fields:
   - [`workspaces`](#specifying-workspaces) - Specifies a set of Workspaces that the `Pipeline` requires.
   - [`tasks`](#adding-tasks-to-the-pipeline):
       - [`name`](#adding-tasks-to-the-pipeline) - the name of this `Task` within the context of this `Pipeline`.
+      - [`displayName`](#adding-tasks-to-the-pipeline) - a user-facing name of this `Task` within the context of this `Pipeline`.
+      - [`description`](#adding-tasks-to-the-pipeline) - a description of this `Task` within the context of this `Pipeline`.
       - [`taskRef`](#adding-tasks-to-the-pipeline) - a reference to a `Task` definition.
       - [`taskSpec`](#adding-tasks-to-the-pipeline) - a specification of a `Task`.
       - [`resources`](#specifying-resources-in-pipelinetasks) - Specifies the [`PipelineResource`](resources.md) that
@@ -113,10 +115,13 @@ A `Pipeline` definition supports the following fields:
         multiple `TaskRuns` or `Runs`.
   - [`results`](#emitting-results-from-a-pipeline) - Specifies the location to which the `Pipeline` emits its execution
     results.
+  - [`displayName`](#specifying-a-display-name) - is a user-facing name of the pipeline that may be used to populate a UI.
   - [`description`](#adding-a-description) - Holds an informative description of the `Pipeline` object.
   - [`finally`](#adding-finally-to-the-pipeline) - Specifies one or more `Tasks` to be executed in parallel after
     all other tasks have completed.
     - [`name`](#adding-finally-to-the-pipeline) - the name of this `Task` within the context of this `Pipeline`.
+    - [`displayName`](#adding-finally-to-the-pipeline) - a user-facing name of this `Task` within the context of this `Pipeline`.
+    - [`description`](#adding-finally-to-the-pipeline) - a description of this `Task` within the context of this `Pipeline`.
     - [`taskRef`](#adding-finally-to-the-pipeline) - a reference to a `Task` definition.
     - [`taskSpec`](#adding-finally-to-the-pipeline) - a specification of a `Task`.
     - [`retries`](#using-the-retries-field) - Specifies the number of times to retry the execution of a `Task` after
@@ -1169,6 +1174,19 @@ In particular:
 > Consider using replacement features instead. Read more in [documentation](migrating-v1alpha1-to-v1beta1.md#replacing-pipelineresources-with-tasks)
 > and [TEP-0074](https://github.com/tektoncd/community/blob/main/teps/0074-deprecate-pipelineresources.md).
 
+## Specifying a display name
+
+The `displayName` field is an optional field that allows you to add a user-facing name of the `Pipeline` that can be used to populate a UI. For example:
+
+```yaml
+spec:
+  displayName: "Code Scan"
+  tasks:
+    - name: scan
+      taskRef:
+        name: sonar-scan
+```
+
 ## Adding a description
 
 The `description` field is an optional field and can be used to provide description of the `Pipeline`.

diff --git a/docs/tasks.md b/docs/tasks.md
@@ -28,6 +28,7 @@ weight: 201
   - [Specifying `Volumes`](#specifying-volumes)
   - [Specifying a `Step` template](#specifying-a-step-template)
   - [Specifying `Sidecars`](#specifying-sidecars)
+  - [Specifying a `DisplayName`](#specifying-a-display-name)
   - [Adding a description](#adding-a-description)
   - [Using variable substitution](#using-variable-substitution)
     - [Substituting parameters and resources](#substituting-parameters-and-resources)
@@ -1072,6 +1073,10 @@ was executing before receiving a "stop" signal, the `Sidecar` keeps
 running, eventually causing the `TaskRun` to time out with an error.
 For more information, see [issue 1347](https://github.com/tektoncd/pipeline/issues/1347).
 
+### Specifying a display name
+
+The `displayName` field is an optional field that allows you to add a user-facing name to the task that may be used to populate a UI.
+
 ### Adding a description
 
 The `description` field is an optional field that allows you to add an informative description to the `Task`.