-
Notifications
You must be signed in to change notification settings - Fork 221
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Tekton Enhancement Proposals proposal 🤴 #82
Conversation
teps/README.md
Outdated
@@ -0,0 +1,6 @@ | |||
# Kubernetes Enhancement Proposals (TEPs) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/Kubernetes/Tekton/ ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lol 😹
- an overall project development roadmap | ||
- motivation for impactful user facing changes | ||
- reserve GitHub issues for tracking work in flight rather than | ||
creating "umbrella" issues |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we link to something here for the term "umbrella"? I follow what you're saying but perhaps we could make it very concrete as to what is being conveyed here.
One overall comment which is anecdotal so take it for what it is worth. We tried to do this internally and we found the PR format was not ideal for seeking feedback (github comments are coarser and harder to thread properly) but it was great for versioning and state. We ended up with a hybrid approach where proposals would iterate in docs and then be pushed into the repo when they were "approved". It worked well for us. |
Right, nothing prevent for a smaller group to prepare the design doc using another medium before submitting as a TEP. |
- [Prior Art](#prior-art) | ||
- [Drawbacks](#drawbacks) | ||
- [Alternatives](#alternatives) | ||
- [GitHub issues vs. TEPs](#github-issues-vs-keps) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This link is broken keps
-> teps
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Once we're ready to merge this, this PR should also update :
- https://github.com/tektoncd/community/blob/master/process.md#proposing-features
- maybe the main README in this repo
In other projects:
- Contributing guides like https://github.com/tektoncd/pipeline/blob/master/CONTRIBUTING.md which link here
- maybe the api compatibility policy too re. api changes? https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md#approving-api-changes
I'm wondering if we could make this incrementally more complex instead of adding it all at once, for example adding roles such as "TEP editor" and also the number of states and metadata items (tho maybe these are all well established and its better for us to just follow along)
And to go out on a limb, I'm thinking a bunch of the content of this proposal might be copied from https://github.com/nokia/kubernetes-community/blob/master/keps/0001-kubernetes-enhancement-proposal-process.md and maybe doesnt need to be completely copied in here, maybe just linked?
It'd be nice to avoid repeating stuff that we don't need (esp if its not even an accurate representation of how this community feels - or maybe it is? hard to tell cuz it's copy-pasted) - and give it a tekton community feel
Requests:
Can we include explicit requirements for:
- the same requirements from https://github.com/tektoncd/community/blob/master/process.md#proposing-features (use cases, requirements, alternatives)
- API change approval policy from Pipelines for Pipelines changes https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md#approving-api-changes
Before this proposal, there is not a standard way or template | ||
to create project enhancements. We rely on | ||
documents hosted on Google docs, without a standard template explaining | ||
the change. Once a proposal is done, via a design docs, it tends |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
well we did have https://github.com/tektoncd/community/blob/master/process.md#proposing-features
totally agree that was very lightweight but it wasnt like there wasnt anything
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good point, I should point to that in this doc 😉
|
||
Taking a cue from the [Python PEP process][], we define the role of a | ||
TEP editor. The job of an TEP editor is likely very similar to the | ||
[TEP editor responsibilities][] and will hopefully provide another |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
links TBD i guess?
perhaps it would be reasonable to invest in providing support to those | ||
unfamiliar with this tooling. It also make the proposal document more | ||
accessible that what it is before this proposal, as you are required | ||
to be part of tekton-users@ or tekton-dev@ google groups to see the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maybe link to community docs re. mailing lists
teps/README.md
Outdated
A Tekton Enhancement Proposal (TEP) is a way to propose, communicate and coordinate on new efforts for the Tekton project. | ||
You can read the full details of the project in [TEP-1](0001-tekton-enhancement-proposal-process.md). | ||
|
||
This process is still in a _beta_ state and is mandatory for all enhancements beginning release 1.0. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what is release 1.0?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it would be the first GA of tekton pipelines… But I need to rework this part, as it's not yet clear what we will call GA for tekton 🙃
[design proposals]: https://github.com/kubernetes/community/tree/master/contributors/design-proposals | ||
|
||
## Stewardship | ||
The following DACI model indentifies the responsible parties for TEPs: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was looking for a link to a more neutral web page, the the wikipedia like doesn't say too much: https://en.wikipedia.org/wiki/Responsibility_assignment_matrix#DACI
**Workstream** | **Driver** | **Approver** | **Contributor** | | ||
**Informed** --- | --- | --- | --- | --- | ||
| TEP Process Stewardship | TG members | TG members | TG members | Community | | ||
| Enhancement delivery | Enhancement Owner | SIG leadership (SIG Chairs + TLs) | Enhancement Implementer(s) (may overlap with Driver) | Community | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we dont really have SIGs, maybe we can replace this with OWNERS from each project?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, that's what I was going for 🙃
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CDF SIGs may be drivers and/or contributors of a change, but I'm not sure we need to explicitly call out their role in TEPs.
As @pierretasci I'm a bit concerned about this as well - I'm willing to give it a shot! I like the idea of having more formal guidance around what folks should put in a proposal, but @vdemeester I had to admit I don't quite understand the motivation for making this change, as we could have a recommended google docs template and it'd accomplish a lot of the same thing. I'm thinking the main motivations for putting docs in github are:
|
Indeed those are the main motivations:
Yes definitely 👍 I took an heavy inspiration on KEP and didn't clean all the things before having initial feedbacks 👼
My end-goal is to say "this is similar to KEP", but having our own process, that we agreed on, so the document should be self-describing and shouldn't make user need to read the KEP process to understand this one.
Yep, as commented before, I'll clean things that are not needed 👍
👍 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for doing this!
- design document | ||
|
||
into one file which is created incrementally in collaboration with one | ||
or more Working Groups (WGs). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps add a link to the list of existing WGs? Do we have one?
The purpose of the TEP process is to reduce the amount of "tribal | ||
knowledge" in our community. By moving decisions from a smattering of | ||
mailing lists, video calls and hallway conversations into a well | ||
tracked artifact, this process aims to enhance communication and | ||
discoverability. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+100
This is very important - TEP are not necessarily about improving the process of designing a feature - but rather about visibility and transparency
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like most of this section but I feel myself feeling really defensive when I read this sentence "By moving decisions from a smattering of mailing lists, video calls and hallway conversations into a well tracked artifact", it just feels really pejorative toward the processes we've been using up until this point. Is there something different we can say that is maybe a bit more complimentary toward our existing processes (if they deserve it? i think they do! im proud of what we have done) - or maybe drop this sentence? (keeping the "tribal knowledge" sentence tho)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can drop the sentence or write it better and keep "tribal knowledge" yes. I'll.. try to come with a better sentence 😉. (sorry if it feels "very pejorative" 😅 it's not meant to be)
[design proposals]: https://github.com/kubernetes/community/tree/master/contributors/design-proposals | ||
|
||
## Stewardship | ||
The following DACI model indentifies the responsible parties for TEPs: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was looking for a link to a more neutral web page, the the wikipedia like doesn't say too much: https://en.wikipedia.org/wiki/Responsibility_assignment_matrix#DACI
**Workstream** | **Driver** | **Approver** | **Contributor** | | ||
**Informed** --- | --- | --- | --- | --- | ||
| TEP Process Stewardship | TG members | TG members | TG members | Community | | ||
| Enhancement delivery | Enhancement Owner | SIG leadership (SIG Chairs + TLs) | Enhancement Implementer(s) (may overlap with Driver) | Community | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CDF SIGs may be drivers and/or contributors of a change, but I'm not sure we need to explicitly call out their role in TEPs.
operator facing enhancement should follow the TEP process. If an | ||
enhancement would be described in either written or verbal | ||
communication to anyone besides the TEP author or developer, then | ||
consider creating a TEP. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think I fully understand the meaning of this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This means : if a proposal needs to be shared with more than just the developer (for different reason : cross-project, collaboration, user-facing), then it needs to have a TEP.
through the TEP process. WGs may find it helpful to enumerate what | ||
_does not_ require a TEP rather than what does. WGs also have the | ||
freedom to customize the TEP template according to their WG specific | ||
concerns. For example, the TEP template used to track API changes will |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We still might want to include a list of sections that should be adopted by all WGs
4071aac
to
7a3bce4
Compare
All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the ℹ️ Googlers: Go here for more info. |
implement it in the main project(s). This state doesn't prevent using | ||
`tektoncd/experimental` to *experiment* and gather feedback. | ||
|
||
A TEP can be created with the `implementable` state if it doesn't need |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NIT: Maybe reword to something like: A TEP can be moved to the implementable
state if it doesn't need any more discussion and is approved as is.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for this latest updates!
The template looks good to me, there are a few comments that might be worth addressing if you want to do one last quick iteration, but up to you.
/lgtm
- [Drawbacks](#drawbacks) | ||
- [Alternatives](#alternatives) | ||
- [Infrastructure Needed (optional)](#infrastructure-needed-optional) | ||
<!-- /toc --> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what about an optional upgrade / migration strategy section?
|
||
## Examples | ||
|
||
Let's give some example of workflow to give reader a better |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NIT: change "give reader" to "give the reader"
## Examples | ||
|
||
Let's give some example of workflow to give reader a better | ||
understanding on how and when TEP should be created and how they are |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NIT: change "when TEP" to "when a TEP"
understanding on how and when TEP should be created and how they are | ||
managed across time. | ||
|
||
Those are examples, and do not necessarily reflect what happened, or |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NIT: Change "Those are examples" to "These are examples"
managed across time. | ||
|
||
Those are examples, and do not necessarily reflect what happened, or | ||
will happens on the particular subject they are about. They are here |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NIT: Change "will happens" to "what will happen"
|
||
Those are examples, and do not necessarily reflect what happened, or | ||
will happens on the particular subject they are about. They are here | ||
to give more context and ideas on different situation that could rise |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NIT: Change "situation" to "situations"
NIT: Change "could rise" to "could arise"
### Prior Art | ||
|
||
The TEP process as proposed was essentially adapted from the | ||
[Kubernetes KEP process][], which itself is essentially stolen from the [Rust RFC |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this process apply to all Tekton projects in addition to Pipelines like CLI, triggers, dashboard? if so, should we store TEPs in a project specific directories like KEP?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It applies to all tekton project, but so far, trying to keep it simple and have it all on the same folder.
- We may have a lot of TEP that touch more than one project
- We are not as big as kubernetes 😝
We'll see over time if we need to have subfolders, etc..
This is the proposal to define a well defined, more "accessible" proposal workflow for Tekton cross-project enhancement (and new projects). Co-Authored-By: Daniel Helfand <[email protected]> Co-Authored-By: Napoleon Santana <[email protected]> Signed-off-by: Vincent Demeester <[email protected]>
- Clean some non-sense and make it as small, simple and clear as possible - Make sure the process doesn't block authors to use other means to write design docs before proposing a TEP - Add some examples (fictional but based on real enhancements / subjects) Signed-off-by: Vincent Demeester <[email protected]>
- Adding some examples of not requiring a TEP - typos and work fixes Signed-off-by: Vincent Demeester <[email protected]>
This should allow user to update toc.sh of there TEPs automatically 😉 Signed-off-by: Vincent Demeester <[email protected]>
Signed-off-by: Vincent Demeester <[email protected]>
Signed-off-by: Vincent Demeester <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking great! As far as I can tell @afrittoli @imjasonh and @abayer are all in favor, and me as well, and all major feedback has been addressed so it feels like it's time we put this to use :D
/lgtm
- the fact that the what constitutes a feature is still undefined | ||
- issue management | ||
- the difference between an accepted design and a proposal | ||
- the organization of design proposals |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
bumping this, but not enough to block merging on!
And since I think everyone has had a look: /hold cancel |
just realized @abayer hasn't had a look yet /hold |
aaaand it was merged. okay well. hopefully @abayer doesnt have any objections that cant be addressed in followup PRs 😨 /hold cancel |
I do not have any objections. =) |
A copy (for historical purposes) of the original PDF can be found within the sigstore/TSC repository, but the canonical version of the charter has been converted to Markdown and is viewable at https://github.com/sigstore/TSC/blob/main/docs/CHARTER.MD Signed-off-by: Bob Callaway <[email protected]>
This is the proposal to define a well defined, more "accessible"
proposal workflow for Tekton cross-project enhancement (and new
projects).
In a gist, this is heavily inspired/taken from the
KEP
from Kubernetes. You can also think ofPEP
, RustRFC
s, …This proposal aims to make enhancement proposal easier to track and more acessible.
It should help track what are the proposal, what state they are in and what is the history being those proposals (comments, commit history, …). It's also more accessible as it will be easier for user to comment (only need a GitHub acconut) and read (anonymous) — in the current "not really process", you need to be a member of
tekton-users@
to read andtekton-dev@
to comment.This would replace the general design docs for anything related to a new project or cross-project work — at least initially.
Once we define a template, it should also make it easier to have design docs / enhancement proposa that have a well defined structure.
/cc @bobcatfish @skaegi @sbwsg @dibyom @afrittoli @imjasonh @abayer @sthaha @a-roberts @danielhelfand @mnuttall @ncskier
(Please ping anyone you think I forgot)
.github/
templates 😈)/kind design
/kind documentation
/area roadmap
Signed-off-by: Vincent Demeester [email protected]