Skip to content

Commit

Permalink
Update design principles guidance on conformance
Browse files Browse the repository at this point in the history
This commit clarifies our design principles on conformance to specify
that proposals should in general make Tekton more platform-agnostic,
that existing Kubernetes-isms in the Tekton API shouldn't be used as examples to add more,
and that expecting the user to understand how the API is implemented is something of an
anti-pattern. This commit also updates the TEP template to include questions on conformance.
  • Loading branch information
lbernick authored and tekton-robot committed May 26, 2022
1 parent 0fb84a0 commit 025edb3
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 1 deletion.
10 changes: 9 additions & 1 deletion design-principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,5 +28,13 @@

## Conformance
1. Tekton features should work as the user expects in varied environment setup.
1. Tekton should not contain kubernetes-specific features, such as configuations for a `Pod`, in the API as much as possible. When kubernetes-specific features have to be added, they should be explicitly called out in the design docs and consider shunting them together into a section of the API, such as `podTemplate`.
1. Tekton users should not need to understand the implementation details of the API on any specific platform.
In general, TEPs should make Tekton more platform-agnostic, not more platform-specific.
1. To the greatest extent possible, the Tekton API should not contain Kubernetes-specific features, such as configuration for `Pods`.
While the "main" implementation of the Tekton API is built on Kubernetes, there is also (for example) a [buildkit implementation](https://github.com/vdemeester/buildkit-tekton)
of Tekton, and platform builders may choose to implement the Tekton API in other ways that don't rely on Kubernetes.
When Kubernetes-specific features have to be added, they should be explicitly called out in the design docs, and consider shunting them together into a section of the API, such as `podTemplate`.
The Tekton API currently contains some Kubernetes-isms. These should be treated as potentential long-term opportunities for improvement of our abstractions.
1. In TEPs, discuss how the proposal affects [conformance](https://github.com/tektoncd/community/blob/main/teps/0012-api-spec.md).
As mentioned in the conformance document, newly added API fields shouldn't be required for Tekton conformance, but can
transition to becoming required over time.
11 changes: 11 additions & 0 deletions teps/tools/tep-template.md.template
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,17 @@ required for these dependencies?
their own choices?
-->

### Conformance

<!--
https://github.com/tektoncd/community/blob/main/design-principles.md#conformance

- Does this proposal require the user to understand how the Tekton API is implemented?
- Does this proposal introduce additional Kubernetes concepts into the API? If so, is this necessary?
- If the API is changing as a result of this proposal, what updates are needed to the
[API spec](https://github.com/tektoncd/pipeline/blob/main/docs/api-spec.md)?
-->

### User Experience

<!--
Expand Down

0 comments on commit 025edb3

Please sign in to comment.