From 499383904fd338c1fa21c21c807f4a58ce2b0f65 Mon Sep 17 00:00:00 2001 From: Matt Moore Date: Thu, 19 Aug 2021 10:53:04 -0700 Subject: [PATCH 1/3] Proposal: Support `.` in param / result names --- ...port-domainscoped-parameterresult-names.md | 165 ++++++++++++++++++ teps/README.md | 1 + 2 files changed, 166 insertions(+) create mode 100644 teps/0080-support-domainscoped-parameterresult-names.md diff --git a/teps/0080-support-domainscoped-parameterresult-names.md b/teps/0080-support-domainscoped-parameterresult-names.md new file mode 100644 index 000000000..ec347925a --- /dev/null +++ b/teps/0080-support-domainscoped-parameterresult-names.md @@ -0,0 +1,165 @@ +--- +status: proposed +title: Support domain-scoped parameter/result names +creation-date: '2021-08-19' +last-updated: '2021-08-19' +authors: +- '@mattmoor' +--- + +# TEP-0080: Support domain-scoped parameter/result names + + +- [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) +- [Implementation Pull request(s)](#implementation-pull-request-s) +- [References (optional)](#references-optional) + + +## Summary + +Allow Task and Pipeline authors to expose parameters and results that allow +`.` characters. + +> _This TEP was originally raised [here](https://github.com/tektoncd/pipeline/issues/3590) +as an issue for discussion._ + +## Motivation + +The motivation of this work is to *enabl* us to establish conventions around the +definition of parameters and results that may have a deeper meaning for +higher-level systems without a high-degree of accidental naming collisions. + +The pursuit of `.` is specifically to follow the precedents set by many other systems +(including Kubernetes labels, CloudEvent types, Java import paths, ContainerD plugins, +and many more) of using a Domain-scoped naming convention to "claim" a segment of +names for the owner's exclusive use. This is of course conventional, but in practice +is generally good enough. + +With this work, higher-level systems could start to define Task/Pipeline "interfaces" +or leverage partial signature matching to enable special semantics around certain +signatures, without (significant) concerns around matching something accidentally. + +> _It is notable that with @bobcatfish [TEP for stronger +typing](https://github.com/tektoncd/community/pull/479) that these conventions should +also establish the types associated with those parameter names, and might form a good +case for SchemaRefs._ + +### Goals + +Enable conventions to be established around the use of domain-scoped names as a way +for the domain owner to "own" the definition of what those parameters and results are +for and how they will be used. + +### Non-Goals + +It is not a goal of this TEP to establish these conventions, or begin to define any +"well known" parameters or results owned by Tekton (e.g. `dev.tekton.foo.bar`). + + +### Use Cases (optional) + +See the [original issue](https://github.com/tektoncd/pipeline/issues/3590) for some +of these. + +There are potentially a lot more things like this, but I'd rather leaves those for +a conversation around the types of conventions we should standardize, and not rat hole +here (just about enabling that next convo). + +## Requirements + +Parameters and Result name resolution must be unamiguous, especially in the presence +of proposals like [TEP for stronger typing](https://github.com/tektoncd/community/pull/479), +which allows folks to access fields of complex parameters. + +## Proposal + +Two parts to the proposal: + +1. Allow folks to define parameters and results with `.` in the name: +```yaml + params: + - name: dev.mattmoor.foo +``` + +2. Allow folks to reference parameters and results with quotes around the name +(required if it contains a `.`): +```yaml + steps: + - image: $(params."dev.mattmoor.foo") +``` + +### Notes/Caveats (optional) + +### Risks and Mitigations + +The main risk is likely the ambiguity of references without the quoting requirement, +especially in a world where parameter and results can themselves be object and parts +of those are accessed via `.` + +### User Experience (optional) + +This likely doesn't affect UX much beyond it needing to support the expanded set +of names. Ultimately, this could enable higher-level UX's that are (IMO) much +better than the status quo. + +### Performance (optional) + +N/A + +## Design Details + +This mostly feels like a plumbing exercise, but I'd be happy to expand if there are +specifics worth fleshing out in advance of PRs. + +## Test Plan + +Testing should be added of each of the pieces above: quoting (alone), and quoting +of parameters and results with `.` in both Task and Pipeline contexts. + +## Design Evaluation + +Conformant Tekton implementations should support this. + +## Drawbacks + +The need to quote parameters names may not come intuitively to Task authors, but +if this becomes a well established precedent that's adopted in places like the +catalog there will be ample examples demonstrating how to use this properly. + +## Alternatives + +We could establish conventions around non-domain names (such as `s/[.]/-/`), but this +feels like a less natural convention given the strong precedent for domains. + +## Infrastructure Needed (optional) + +N/A + +## Upgrade & Migration Strategy (optional) + +I can't think of any problems, since this isn't supported today. + +## Implementation Pull request(s) + +Not there yet! + +## References (optional) + +[Original issue](https://github.com/tektoncd/pipeline/issues/3590) \ No newline at end of file diff --git a/teps/README.md b/teps/README.md index 30bfcad84..c172d9c33 100644 --- a/teps/README.md +++ b/teps/README.md @@ -221,3 +221,4 @@ This is the complete list of Tekton teps: |[TEP-0071](0071-custom-task-sdk.md) | Custom Task SDK | proposed | 2021-06-15 | |[TEP-0072](0072-results-json-serialized-records.md) | Results: JSON Serialized Records | implementable | 2021-07-26 | |[TEP-0073](0073-simplify-metrics.md) | Simplify metrics | proposed | 2021-06-23 | +|[TEP-0080](0080-support-domainscoped-parameterresult-names.md) | Support domain-scoped parameter/result names | proposed | 2021-08-19 | From 818added2cf99f0791fee4e4c1e46dfd9f7fd07e Mon Sep 17 00:00:00 2001 From: Matt Moore Date: Mon, 30 Aug 2021 12:45:55 -0700 Subject: [PATCH 2/3] Fix typo --- teps/0080-support-domainscoped-parameterresult-names.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/teps/0080-support-domainscoped-parameterresult-names.md b/teps/0080-support-domainscoped-parameterresult-names.md index ec347925a..0b313166b 100644 --- a/teps/0080-support-domainscoped-parameterresult-names.md +++ b/teps/0080-support-domainscoped-parameterresult-names.md @@ -42,7 +42,7 @@ as an issue for discussion._ ## Motivation -The motivation of this work is to *enabl* us to establish conventions around the +The motivation of this work is to *enable* us to establish conventions around the definition of parameters and results that may have a deeper meaning for higher-level systems without a high-degree of accidental naming collisions. From eb06efe112e2ad8920027e4b3b831a32b09ccf09 Mon Sep 17 00:00:00 2001 From: Matt Moore Date: Mon, 30 Aug 2021 12:50:00 -0700 Subject: [PATCH 3/3] Replace quoting with subscript --- teps/0080-support-domainscoped-parameterresult-names.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/teps/0080-support-domainscoped-parameterresult-names.md b/teps/0080-support-domainscoped-parameterresult-names.md index 0b313166b..5148cddb7 100644 --- a/teps/0080-support-domainscoped-parameterresult-names.md +++ b/teps/0080-support-domainscoped-parameterresult-names.md @@ -98,11 +98,11 @@ Two parts to the proposal: - name: dev.mattmoor.foo ``` -2. Allow folks to reference parameters and results with quotes around the name +2. Allow folks to reference parameters and results with subscript around the name (required if it contains a `.`): ```yaml steps: - - image: $(params."dev.mattmoor.foo") + - image: $(params[dev.mattmoor.foo]) ``` ### Notes/Caveats (optional)