diff --git a/teps/0047-pipeline-task-display-name.md b/teps/0047-pipeline-task-display-name.md new file mode 100644 index 000000000..45381c3c1 --- /dev/null +++ b/teps/0047-pipeline-task-display-name.md @@ -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 +--- + + + +- [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 (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 \ No newline at end of file diff --git a/teps/README.md b/teps/README.md index e7a7e5c3f..663cd3312 100644 --- a/teps/README.md +++ b/teps/README.md @@ -170,6 +170,7 @@ This is the complete list of Tekton teps: |[TEP-0039](0039-add-variable-retries-and-retrycount.md) | Add Variable `retries` and `retry-count` | proposed | 2021-01-31 | |[TEP-0040](0040-ignore-step-errors.md) | Ignore Step Errors | proposed | 2021-02-04 | |[TEP-0045](0045-whenexpressions-in-finally-tasks.md) | WhenExpressions in Finally Tasks | implementable | 2021-01-28 | +|[TEP-0047](0047-pipeline-task-display-name.md) | Pipeline Task Display Name | proposed | 2021-02-10 | |[TEP-0050](0050-ignore-task-failures.md) | Ignore Task Failures | proposed | 2021-02-19 | |[TEP-0051](0051-ppc64le-architecture-support.md) | ppc64le Support | proposed | 2021-01-28 | |[TEP-0052](0052-tekton-results-automated-run-resource-cleanup.md) | Tekton Results: Automated Run Resource Cleanup | proposed | 2021-02-11 |