From 19a7a123a03c4d2bd902e1de848eb33e9fbe0320 Mon Sep 17 00:00:00 2001 From: Ian Tewksbury Date: Tue, 26 Jan 2021 15:52:00 -0500 Subject: [PATCH] Add TEP - 0044-pipeline-task-display-name --- teps/0044-pipeline-task-display-name.md | 145 ++++++++++++++++++++++++ teps/README.md | 1 + 2 files changed, 146 insertions(+) create mode 100644 teps/0044-pipeline-task-display-name.md diff --git a/teps/0044-pipeline-task-display-name.md b/teps/0044-pipeline-task-display-name.md new file mode 100644 index 000000000..4c4e37bd5 --- /dev/null +++ b/teps/0044-pipeline-task-display-name.md @@ -0,0 +1,145 @@ +--- +status: proposed +title: Pipeline Task Display Name +creation-date: '2021-01-28' +last-updated: '2021-01-28' +authors: +- '@itewk' +--- + +# TEP-0044: Pipeline Task Display Name + + +- [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) + + +## Summary + +A task in a Pipeline is currently represented in the UI using a field (`name`) that is meant to be +machine readable, not human readable. There should be the addition of a new +optional field (`displayName`) to describe Pipeline tasks that are human readable. + +## Motivation + +Simple version, humans want to read task names formatted for human's not computers, and they want +to see the full task name rendered in their UI. + + +The longer version, 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 +capitalization, and the entire task name isn't even readable beyond 20 or so characters. + +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 `Pipeline.tasks.*.displayName` (or similar) field that allows any text and + if provided will be rendered when displaying Tekton Pipeline in UI rather then the + machine readable `Pipeline.tasks.*.name` field. +* Ideally when rendering this new display name it will be fully rendered rather then the + current truncation to 20 characters that is currently happening. + +### Non-Goals + +To be determined. + +### Use Cases (optional) + +Pipeline writers can specify a display name for any/all tasks, if supplied that display name +will be rendered in UI rather then the machine readable `name` field value. + +#### Example +``` +kind: PipelineRun +spec: + pipelineSpec: + tasks: + - name: echo-message + displayName: Echo Message + taskSpec: + steps: + - name: echo + image: ubuntu + script: | + echo "Hi!" +``` + +## Requirements + +New display name filed would be optional and accept any unicode character + +## Proposal + +Add `Pipeline.tasks.*.displayName` and update Tekton rendering to use that field rather then +`Pipeline.tasks.*.name` when provided. + +### Notes/Caveats (optional) + +None. + +### Risks and Mitigations + +If pursue always rendering the full display name, for extremly large stings could start to cause +rendering issues. Mitigations would be to look out how other similar tools solve this problem. + +### User Experience (optional) + +None. + +### Performance (optional) + +Non predicted. + +## Design Details + +Suggested new parameter would be `Pipeline.tasks.*.displayName` and the required changes to the +Tekton Pipeline rendering to take advantage of the new field. + +## Test Plan + +To be determined. + +## Design Evaluation +This affects UX making Tekton pipeline run rendering more end user consumable. + +## Drawbacks +None. + +## Alternatives +None. + +## Infrastructure Needed (optional) +None. + +## Upgrade & Migration Strategy (optional) +None. + +## References (optional) +https://github.com/tektoncd/pipeline/issues/3466#issuecomment-767786717 \ No newline at end of file diff --git a/teps/README.md b/teps/README.md index 2ac3a40e5..5171cda25 100644 --- a/teps/README.md +++ b/teps/README.md @@ -147,3 +147,4 @@ This is the complete list of Tekton teps: |[TEP-0032](0032-tekton-notifications.md) | Tekton Notifications | proposed | 2020-11-18 | |[TEP-0035](0035-document-tekton-position-around-policy-authentication-authorization.md) | document-tekton-position-around-policy-authentication-authorization | implementable | 2020-12-09 | |[TEP-0036](0036-start-measuring-tekton-pipelines-performance.md) | Start Measuring Tekton Pipelines Performance | proposed | 2020-11-20 | +|[TEP-0044](0044-pipeline-task-display-name.md) | Pipeline Task Display Name | proposed | 2021-01-28 |