-
Notifications
You must be signed in to change notification settings - Fork 221
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add TEP - 0047-pipeline-task-display-name
- Loading branch information
Showing
2 changed files
with
183 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,182 @@ | ||
| --- | ||
| status: proposed | ||
| title: Pipeline Task Display Name | ||
| creation-date: '2021-01-28' | ||
| last-updated: '2021-02-10' | ||
| authors: | ||
| - '@itewk' | ||
| --- | ||
|
|
||
| # TEP-0047: Pipeline Task Display Name | ||
| --- | ||
|
|
||
|
|
||
| <!-- toc --> | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Goals](#goals) | ||
| - [Non-Goals](#non-goals) | ||
| - [Use Cases (optional)](#use-cases-optional) | ||
| - [Requirements](#requirements) | ||
| - [Proposal](#proposal) | ||
| - [Notes/Caveats (optional)](#notescaveats-optional) | ||
| - [Risks and Mitigations](#risks-and-mitigations) | ||
| - [User Experience (optional)](#user-experience-optional) | ||
| - [Performance (optional)](#performance-optional) | ||
| - [Design Details](#design-details) | ||
| - [Test Plan](#test-plan) | ||
| - [Design Evaluation](#design-evaluation) | ||
| - [Drawbacks](#drawbacks) | ||
| - [Alternatives](#alternatives) | ||
| - [Infrastructure Needed (optional)](#infrastructure-needed-optional) | ||
| - [Upgrade & Migration Strategy (optional)](#upgrade--migration-strategy-optional) | ||
| - [References (optional)](#references-optional) | ||
| <!-- /toc --> | ||
|
|
||
| ## Summary | ||
|
|
||
| A task in a Pipeline is currently represented in the UI (as observed in OpenShift 4.6) | ||
| using a field (`name`) that is meant to be machine readable, not human readable. | ||
| There should be the addition of a way to describe Pipeline tasks that are human readable | ||
| so that any tool that renders Tekton Pipeline can do so using a "human readable" field. | ||
|
|
||
| ## Motivation | ||
|
|
||
| The end user of a Tekton pipeline can vary including but not limited to | ||
| application developer, to security professional, to compliance officer, | ||
| service reliability engineer, product manager, and beyond. The farther | ||
| you move away from the application developer the more important human | ||
| understanding of the CI/CD process is important. | ||
|
|
||
| Currently if a product manager or auditor was to look at a Tekton Pipeline run rendered in UI | ||
| that would be presented with a bunch of truncated machine readable task names, no spaces, | ||
| no special characters, no capitalization because the only option for tools to render these tasks | ||
| is the machine readable `Pipeline.spec.tasks.*.name` field. | ||
|
|
||
| Compare this to other tools in this space, Jenkins, GitLab CI, GitHub Actions, etc. | ||
| Their renderings of their workflows are meant to be human consumable. Their task names have | ||
| the option to be rendered in a human consumable format with use of any characters and fully | ||
| rendered for context. | ||
|
|
||
| ### Goals | ||
|
|
||
| * Add a way to specify an optional display name for `Pipeline.spec.tasks.*.` items that allows | ||
| any text and if provided will be useable by UIs rendering Tekton Piplines rather then the | ||
| machine readable `Pipeline.spec.tasks.*.name` field. | ||
| * Add a way to specify a long form description for `Pipeline.spec.tasks.*.` items that allows for a | ||
| long form description of a task in the context of a `Pipeline` to provide additional | ||
| human context to the intent of a task in a Pipeline. | ||
| * Add a way to specify an optional display name for `Pipeline` objects that allows any text | ||
| and if provided will be useable for UIs rendering Tekton `Pipeline` rather then the | ||
| machine readable `Pipeline.name` field. | ||
| ### Non-Goals | ||
|
|
||
| To be determined. | ||
|
|
||
| ### Use Cases (optional) | ||
|
|
||
| * Pipeline writers can optionally specify a display name for any/all tasks in a `Pipeline`. | ||
| * Pipeline writers can optionally specify a description for any/all tasks in a `Pipeline`. | ||
| * Pipeline writers can optionally specific a display name for a `Pipeline`. | ||
| * Pipeline writers can optionally specify a description for a `Pipeline`. | ||
| ## Requirements | ||
|
|
||
| * New display name filed would be optional and accept any unicode character. | ||
| * New description field would be optional and accept any unicode character. | ||
|
|
||
| ## Proposal | ||
|
|
||
| See goals and alternatives. | ||
| ### Notes/Caveats (optional) | ||
|
|
||
| None. | ||
| ### Risks and Mitigations | ||
|
|
||
| 1. there are limits on the lengths of strings Kubernetes will store which may need some handling | ||
| of some sort | ||
|
|
||
| 2. Tools that render Tekton pipelines will need to be updated to take advantage of the new | ||
| fields once they are available. | ||
| ### User Experience (optional) | ||
|
|
||
| None. | ||
|
|
||
| ### Performance (optional) | ||
|
|
||
| Non predicted. | ||
|
|
||
| ## Design Details | ||
|
|
||
| Suggested new parameters would be: | ||
| * `Pipeline.spec.tasks.*.displayName` | ||
| * `Pipeline.spec.tasks.*.description` | ||
| * `Pipeline.displayName` | ||
| * `Pipeline.description` | ||
|
|
||
| ## Test Plan | ||
|
|
||
| To be determined. | ||
|
|
||
| ## Design Evaluation | ||
| None. | ||
|
|
||
| ## Drawbacks | ||
| None. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| ### Possible solution 1 | ||
| Add new fields to spec. | ||
| ``` | ||
| kind: Pipeline | ||
| metadata: | ||
| name: our-awesome-pipeline | ||
| spec: | ||
| displayName: Our Awesome Pipeline | ||
| description: | | ||
| This is our awesome pipeline that does amazing things. | ||
| tasks: | ||
| - name: setup-pgp-keys | ||
| displayName: SETUP: PGP Keys | ||
| description: | | ||
| Sets up the PGP keys required to decrypt encrypted configuration. | ||
| taskRef: | ||
| kind: ClusterTask | ||
| name: import-pgp-keys | ||
| ``` | ||
|
|
||
| ### Possible solution 2 | ||
| Add `Pipeline.spec.tasks.*.metadata` and add displayName and description annotations to | ||
| `Pipeline.metadata` and `Pipeline.spec.tasks.*.metadata`. | ||
| ``` | ||
| kind: Pipeline | ||
| metadata: | ||
| annotations: | ||
| tekton.dev/displayName: "Clone, Build and Deploy App" | ||
| tekton.dev/description: "CI/CD workflow for ACME apps with high trust" | ||
| spec: | ||
| tasks: | ||
| - name: clone-app | ||
| metadata: | ||
| annotations: | ||
| tekton.dev/displayName: "Clone App" | ||
| tekton.dev/description: "Fetch the App source code that will be tested and built" | ||
| taskRef: | ||
| name: git-clone | ||
| # ... etc ... | ||
| - name: clone-config | ||
| metadata: | ||
| annotations: | ||
| tekton.dev/displayName: "Clone Config" | ||
| tekton.dev/description: "Fetch the deployment config for staging" | ||
| # ... etc ... | ||
| ``` | ||
|
|
||
| ## Infrastructure Needed (optional) | ||
| None. | ||
|
|
||
| ## Upgrade & Migration Strategy (optional) | ||
| None. | ||
|
|
||
| ## References (optional) | ||
| https://github.com/tektoncd/pipeline/issues/3466#issuecomment-767786717 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters