Skip to content
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

Merged
merged 6 commits into from
Jun 5, 2020

Conversation

vdemeester
Copy link
Member

@vdemeester vdemeester commented Mar 6, 2020

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 of PEP, Rust RFCs, …

This proposal aims to make enhancement proposal easier to track and more acessible.

  • provide a common structure for proposing changes to Tekton
  • ensure that the motivation for a change is clear
  • allow for the enumeration stability milestones and stability
    graduation criteria
  • persist project information in a Version Control System (VCS) for
    future Tekton users and contributors
  • support the creation of high value user facing information such
    as:
    • an overall project development roadmap
    • motivation for impactful user facing changes
  • reserve GitHub issues for tracking work in flight rather than
    creating "umbrella" issues
  • ensure community participants are successfully able to drive changes
    to completion across one or more releases while stakeholders are
    adequately represented throughout the process

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 and tekton-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)

  • Simplify some stuff (?)
  • Fixing my english 🇫🇷
  • Define a template file (.github/ templates 😈)

/kind design
/kind documentation
/area roadmap

Signed-off-by: Vincent Demeester vdemeest@redhat.com

@tekton-robot tekton-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 6, 2020
@tekton-robot tekton-robot added kind/design Categorizes issue or PR as related to design. kind/documentation Categorizes issue or PR as related to documentation. area/roadmap Issues that are part of the project (or organization) roadmap (usually an epic) labels Mar 6, 2020
@tekton-robot tekton-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Mar 6, 2020
teps/README.md Outdated
@@ -0,0 +1,6 @@
# Kubernetes Enhancement Proposals (TEPs)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/Kubernetes/Tekton/ ?

Copy link
Member Author

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
Copy link
Member

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.

teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
@pierretasci
Copy link
Contributor

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.

@vdemeester
Copy link
Member Author

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)
Copy link
Member

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 ?

Copy link
Contributor

@bobcatfish bobcatfish left a 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 :

In other projects:

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:

  1. the same requirements from https://github.com/tektoncd/community/blob/master/process.md#proposing-features (use cases, requirements, alternatives)
  2. 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
Copy link
Contributor

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

Copy link
Member Author

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
Copy link
Contributor

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
Copy link
Contributor

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.
Copy link
Contributor

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?

Copy link
Member Author

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 🙃

teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
[design proposals]: https://github.com/kubernetes/community/tree/master/contributors/design-proposals

## Stewardship
The following DACI model indentifies the responsible parties for TEPs:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

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 |
Copy link
Contributor

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?

Copy link
Member Author

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 🙃

Copy link
Member

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.

@bobcatfish
Copy link
Contributor

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.

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:

  1. One place to look to find the docs
  2. Revision history that's easier to navigate (not 100% sure that's true)
  3. Don't have to be in tekton-dev to see the docs?

@vdemeester
Copy link
Member Author

[…] 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:

1. One place to look to find the docs

2. Revision history that's easier to navigate (not 100% sure that's true)

3. Don't have to be in tekton-dev to see the docs?

Indeed those are the main motivations:

  1. having a central places for all the docs
  2. all the docs more accessible (available for everybody as read-only at least)
  3. proposal, enhancement on proposals, taking over a proposal, are all done the same way : opening a PR 🙃
  4. Revision history, comments history, etc… at least for comments it is true 🙃 (it's kinda really hard to see historical comments on a google docs)

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)

Yes definitely 👍 I took an heavy inspiration on KEP and didn't clean all the things before having initial feedbacks 👼

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?

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.

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

Yep, as commented before, I'll clean things that are not needed 👍

Can we include explicit requirements for:

1. the same requirements from https://github.com/tektoncd/community/blob/master/process.md#proposing-features (use cases, requirements, alternatives)

2. API change approval policy from Pipelines for Pipelines changes https://github.com/tektoncd/pipeline/blob/master/api_compatibility_policy.md#approving-api-changes

👍

Copy link
Member

@afrittoli afrittoli left a 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).
Copy link
Member

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?

Comment on lines 93 to 101
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.
Copy link
Member

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

Copy link
Contributor

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)

Copy link
Member Author

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:
Copy link
Member

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 |
Copy link
Member

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.

Comment on lines 125 to 128
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.
Copy link
Member

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?

Copy link
Member Author

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
Copy link
Member

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

teps/0001-tekton-enhancement-proposal-process.md Outdated Show resolved Hide resolved
@googlebot
Copy link

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 @googlebot I consent. in this pull request.

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 cla label to yes (if enabled on your project).

ℹ️ 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
Copy link
Contributor

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.

Copy link
Member

@afrittoli afrittoli left a 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 -->
Copy link
Member

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

@mpeters mpeters Jun 4, 2020

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
Copy link
Contributor

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
Copy link
Member

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?

Copy link
Member Author

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.

  1. We may have a lot of TEP that touch more than one project
  2. We are not as big as kubernetes 😝

We'll see over time if we need to have subfolders, etc..

vdemeester and others added 6 commits June 5, 2020 11:36
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 <helfand.4@gmail.com>
Co-Authored-By: Napoleon Santana <popcor255@gmail.com>
Signed-off-by: Vincent Demeester <vdemeest@redhat.com>
- 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 <vdemeest@redhat.com>
- Adding some examples of not requiring a TEP
- typos and work fixes

Signed-off-by: Vincent Demeester <vdemeest@redhat.com>
This should allow user to update toc.sh of there TEPs automatically 😉

Signed-off-by: Vincent Demeester <vdemeest@redhat.com>
Signed-off-by: Vincent Demeester <vdemeest@redhat.com>
Signed-off-by: Vincent Demeester <vdemeest@redhat.com>
@tekton-robot tekton-robot removed the lgtm Indicates that a PR is ready to be merged. label Jun 5, 2020
Copy link
Contributor

@bobcatfish bobcatfish left a 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
Copy link
Contributor

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!

@tekton-robot tekton-robot added the lgtm Indicates that a PR is ready to be merged. label Jun 5, 2020
@bobcatfish
Copy link
Contributor

And since I think everyone has had a look:

/hold cancel

@tekton-robot tekton-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 5, 2020
@bobcatfish
Copy link
Contributor

just realized @abayer hasn't had a look yet

/hold

@tekton-robot tekton-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 5, 2020
@tekton-robot tekton-robot merged commit 1565ac4 into tektoncd:master Jun 5, 2020
@bobcatfish
Copy link
Contributor

aaaand it was merged. okay well. hopefully @abayer doesnt have any objections that cant be addressed in followup PRs 😨

/hold cancel

@tekton-robot tekton-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 5, 2020
@abayer
Copy link
Contributor

abayer commented Jun 5, 2020

I do not have any objections. =)

@bobcatfish
Copy link
Contributor

image

@vdemeester vdemeester deleted the teps-proposal branch June 5, 2020 19:31
dlorenc pushed a commit to dlorenc/community that referenced this pull request Oct 27, 2022
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 <bcallaway@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
approved Indicates a PR has been approved by an approver from all required OWNERS files. area/roadmap Issues that are part of the project (or organization) roadmap (usually an epic) cla: no kind/design Categorizes issue or PR as related to design. kind/documentation Categorizes issue or PR as related to documentation. lgtm Indicates that a PR is ready to be merged. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.