Update governance.md #286
Update governance.md #286
Conversation
|
Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). 📝 Please follow instructions at https://github.com/kubernetes/kubernetes/wiki/CLA-FAQ to sign the CLA. Once you've signed, please reply here (e.g. "I signed it!") and we'll verify. Thanks.
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
k8s-ci-robot
added
cncf-cla: no
|
cc @calebmiles |
|
I agree with all of these points and that they reflect the "reality" of the project today. I am in favor of merging as is so we can iterate on particular parts of the process as we continue to evolve. Approve and lgtm. |
governance.md
Outdated
| - etc... | ||
| Contributors have the opportunity to grow in responsibilities, privileges, and authority corresponding | ||
| to the scope, quality, quantity, and duration of their contributions. Definition of criteria and process | ||
| is in progress, with preliminary requirements below. Any position achieved by merit is achieved by an individual and the authority follows the individual whoever they go, and does not remain with their previous employer(s). |
|
Also in favor of merging so this can be iterated. |
| - Keep up-to-date meeting notes, linked from the SIG's page in the community repo | ||
| - Announce meeting agenda before each meeting and post minutes after, on their SIG mailing list | ||
| - Record SIG meeting and make it publicly available | ||
| - TBD: Some SIG leads have objected to this, and also pointed out that it’s generally less useful |
There was a problem hiding this comment.
Given that the cost of recording is near-zero (at least for hangouts and zoom), perhaps we should leave it to the viewers/consumers of this information as to whether they prefer to watch the video or read the notes. One benefit of recordings is that they are complete, which notes are often not.
There was a problem hiding this comment.
Agree -- my understanding is that people do watch the videos.
There was a problem hiding this comment.
The main objection is that it creates a "chilling effect". There are also complaints about the sum of all these requirements imposing too much work on overburdened engineers. I think the solution to the latter is to get non-eng help for managing SIG logistics.
|
LGTM. Good enough for now. |
| - mentor REVIEWERS and CONTRIBUTORS | ||
| - Benefits | ||
| - TBD: swag | ||
| - **MAINTAINER**: |
There was a problem hiding this comment.
I'm not seeing a huge delta between APPROVERs and MAINTAINERs.
Is this distinction already in use or is this a new "rank" on the ladder?
There was a problem hiding this comment.
Approvers apply to subtrees in the repo -- it's part of the OWNERS mechanism.
Maintainers are for the whole repo and gain a lot of github permissions.
I could easily see twice as many Reviewers as Approvers, and twice as many Approvers as Maintainers.
There was a problem hiding this comment.
I wonder if we could extract REVIEWER and APPROVER (and OWNERmaybe?) from the ladder, and still express their importance. These specifically are about sub-trees, while the rest (seem to be) about the whole repo. They are more like modifiers on MEMBER.
Would that help address the "too many rungs in the ladder" point some were making?
There was a problem hiding this comment.
I don't think removing REVIEWER and APPROVER makes sense. I wouldn't want someone to leap from zero to MAINTAINER.
I'd first remove NEWCOMER and CONTRIBUTOR, which are self-evident, and maybe move OWNER and LEAD elsewhere, since those are much more selective roles.
As a large project, we are going to have more rungs, unless/until we break up the project into small pieces.
| file `maintainers` list | ||
| - committed to the project: Kubernetes is a very high-volume project, with hundreds of PRs and issues | ||
| per week, so expect a significant time commitment | ||
| - nominated by a Champion (see below) from the existing MAINTAINERS, who will find a |
There was a problem hiding this comment.
This process seems new. Is this the current process that we are following or is this something that is being introduced in this edit?
There was a problem hiding this comment.
Yes, it's new, but was iterated on in a prior PR and then again in the doc.
The maintainers group is currently only represented in a github team. The problem with that is that many people can't see who is in that team and almost nobody can observe changes to the team.
The set of maintainers has been frozen since last summer pending some kind of official process.
There was a problem hiding this comment.
If you want, I could remove the interim process, but maintainers would revert to frozen status.
There was a problem hiding this comment.
Wrt github teams -- I think they should be secondary to files that are checked in. In fact, I'd love to see the teams be automatically sync'd based on files so that we have a single source of truth with an audit trail. As things stand, too much of this stuff is grandfathered in and, frankly, Google folks have been added in the past without any community oversight.
As for the "champion" thing -- is that an official role or just part of the process? I think we can simplify this by having less "named" things that people aspire to and have something simpler. The fact that we have sponsors and champions is just confusing and seems overengineered.
There was a problem hiding this comment.
Also -- it would be clearer in the doc if the process for maintaining the list of members for this role (the voting/approval process) were separated from the rights/responsiblities.
Ideally, we could put together a very succinct overview of what the ranks are, a one sentence description of what you can do with that rank and a short description of how you get there. The nitty gritty details can be in the fine print.
There was a problem hiding this comment.
Agreed on having files as the single source of truth. Nice idea.
| API REVIEWER and APPROVER are called out specifically because the API is critical to the | ||
| identity of Kubernetes and is a horizontal area that crosses directories and SIGs. | ||
|
|
||
| - [**API REVIEWER**]: |
There was a problem hiding this comment.
Do these apply to all parts of the k8s community or just the core project? I imagine that as we expand the community there will be APIs that will be owned and driven by other projects that won't be subject to this process.
With that in mind, it may be worthwhile to break this out into a separate document and reference that. Also clarify the scope.
There was a problem hiding this comment.
Someone else can break up this document.
I agree that this is currently written to be focused on the main project/repo. We're going to need to further subdivide our repos into multiple github orgs with distinct rules, I think.
There was a problem hiding this comment.
Obviously, there's some overlap between this and the layers stuff. I think it's pretty unambiguous as-is that this means the public-facing "main" kube API much more than things like plugin APIs or package APIs.
There was a problem hiding this comment.
@bgrant0607 -- I think that breaking this apart now will result in more people reading it and getting better feedback. It is a wall of text and, as such, limits the number of people that are paying attention. We need to make sure we communicate well in addition to getting the details right.
@thockin -- I don't find this unambiguous at all. Right now there is the k8s API but, as we have more projects in the kubernetes ecosystem they will have their own APIs. We need to define the scope for pretty much everything in this document as to if it just applies to kubernetes/kubernetes or to other things that are in kubernetes/* or some other way to describe this.
Are we going to have completely different ranks for kubernetes/api-machinery? What aboutkubernetes/kops?
There was a problem hiding this comment.
I interpret this as the main kubernetes API -- all the parts that are built in, including things like TypeMeta and ObjectMeta, as well as Pods, Services, all the way to apigroups and return values. The user-facing API. This does not cover internal APIs between packages, or CLIs.
As such, I think it is very important to keep a small group of people thinking holistically and across all resources, and to make them the gate for such changes.
| - Benefits | ||
| - design/proposal approval authority for some area of the project, though escalation to LEADS | ||
| is still possible, and beta/GA APIs must still be vetted by API REVIEWERS and APPROVERS | ||
| - **LEAD**: |
There was a problem hiding this comment.
This is a new role that doesn't exist elsewhere. Do we need it? In the Google Doc it was marked as provisional but that is removed here.
Is it not enough to say top level OWNER?
There was a problem hiding this comment.
It does de facto exist.
Originally I had it as the top-level approvers, but ran into a situation in less than a week after writing that where conflating the two caused a problem.
The google3 OWNERS mechanism has at least a convention for adding top-level OWNERS for approving cross-cutting code changes, such as changes to the build system, automated refactorings, etc.
There was a problem hiding this comment.
I'm confused. What was the situation where conflating these caused a problem? And if this 'de-facto exists" where is that list kept and what is the process around that?
| - project decision makers | ||
| - technically can approve virtually any PRs | ||
| - can [Sponsor incubator repos](incubator.md) | ||
| - can Sponsor MAINTAINERS |
There was a problem hiding this comment.
The MAINTAINERS section says that a "Champion" sponsors.
There was a problem hiding this comment.
These are people who can Champion. See Champion section.
I was trying to reuse a common pattern across multiple processes -- review/approve, champion/sponsor -- so as not to introduce too many different ways of doing things.
There was a problem hiding this comment.
The champion vs. sponsor thing is confusing across the doc.
Also, in general, it would be useful to lay this out without creating new named roles but instead just make it part of approval processes. In some ways capitalizing it make it sound more than it is.
As part of the MAINTAINERS process, perhaps say that "New MAINTAINERS are voted in by submitting a PR to modify the XYZ file. This PR must be approved by 3 other MAINTAINERS and at least one LEAD. That LEAD is generally called the "sponsor". Other LEADs have veto power but we expect that to be rarely used."
In this way the idea of sponsor is part o the MAINTAINER process but not something separate. It also doesn't need to be listed in both the MAINTAINER process and in the rights/responsibilities for the LEAD.
| - Keep up-to-date meeting notes, linked from the SIG's page in the community repo | ||
| - Announce meeting agenda before each meeting and post minutes after, on their SIG mailing list | ||
| - Record SIG meeting and make it publicly available | ||
| - TBD: Some SIG leads have objected to this, and also pointed out that it’s generally less useful |
There was a problem hiding this comment.
Agree -- my understanding is that people do watch the videos.
| - TBD: Some SIG leads have objected to this, and also pointed out that it’s generally less useful | ||
| than notes (low information density, not searchable, not skimmable) | ||
| - Ensure the SIG's mailing list and slack channel are archived | ||
| - Report activity in the weekly community meeting at least once every 6 weeks |
There was a problem hiding this comment.
We should be clear about what gets reported. Anything that impacts the project as a whole should be reported. In addition, major (to some definition thereof) features should be checkpointed with the larger group as they go through the various phases including: design doc available, design doc approved, alpha, beta and GA.
The goal should be that members of the community can use these communication points to decide when it makes sense for them to get involved. We have too much going on for anyone to be intimately involved in every feature. But it should be possible for everyone to be aware, at least at the headline level, as major new features and efforts are started and make progress.
There was a problem hiding this comment.
Good topic for umbrella issue.
| - Participate in release planning meetings and retrospectives, and burndown meetings, as needed. | ||
| When the right people aren't present in such meetings, it can put the project at risk, such as | ||
| by slipping the release. | ||
| - Development of new code happens in a project-owned github org and repository, with code and tests |
There was a problem hiding this comment.
We should also state that, unless impossible, all code should work for all members of the community. We should look to avoid the current mess we are in where test infra and release infrastructure only works for Googlers.
There was a problem hiding this comment.
Or the mess with cluster lifecycle tools?
We're going to need help building test and release infra that works for everyone.
We finally have agreement that CNCF could provide resources or funding for resources, at least.
Anyway, good topic for the umbrella doc.
My goal for this doc isn't to solve All Known Problems, but to document the current state and make a modest amount of forward progress.
There was a problem hiding this comment.
The cluster lifecycle tools, while a mess, are at least visible and open to everyone. It is confusing for users but I know that I can at least go off and use those tools if I want to. This is a false equivalency.
But there are a set of tools and processes that are fundamental for how the project works that are centrally controlled by google. We should be actively looking to reduce that and not introduce any more.
So -- I'd love to have something here that states that any systems or infrastructure used for the project shouldn't have dependencies on infrastructure that is only available to a single company.
Concretely -- do non-googlers have access to the machine that runs k8s.io? Can non-googlers push official releases? Do the tools in kubernetes/release work for non-googlers? I understand how this happened but we should look to avoid more of this in the future.
There was a problem hiding this comment.
@jbeda We're aligned on goals, but are drowning in day-to-day fires and need help.
Additionally, while we'd love to hand off responsibilities, such as for running k8s.io, which we're discussing with CNCF, so far we don't have anyone to hand off to.
Some non-Googlers have had access to some resources. For instance, Brendan has access to the kubernetes-jenkins project, which owns the utility cluster where the submit queue runs, and I believe eparis has had access to some resources. We can definitely talk about expanding the permissions to people who'd really be maintaining those systems.
Additionally, nothing is preventing people from creating alternative infrastructure, especially for testing, which we could flip over to at some point. As an example, we've used TravisCI, Shippable, and CircleCI for builds and unit testing in the past, often in parallel. Or, we could just turn off existing infrastructure if that would help incentivize others to replace it. :-)
| Kubernetes | ||
| - Use the above forums as the primary means of working, communicating, and collaborating, as opposed to | ||
| private emails and meetings | ||
| - If used, Google Docs should be made available to everyone on the project. Share them with at least the |
There was a problem hiding this comment.
The docs should be shared with the public -- not just the community. This means that for domains that turn off public sharing (Google), the documents should be recreated with a public gmail account instead. Having to be a member of kubernetes-dev to even read documents runs counter to the community ideals.
There was a problem hiding this comment.
I agree that it's a practical impediment, but disagree that it's counter to our ideals.
I'm ok with changing the guidance here, though.
| SIG discussion group and kubernetes-dev, and it is recommended that they be made public. When sharing | ||
| with kubernetes-dev, do not notify the list, unless it is really an issue that everyone on the project | ||
| should immediately be made aware of. | ||
| - Represent the SIG for the PM group (either a SIG liaison to the PM group or a PM liaison to the SIG): |
There was a problem hiding this comment.
This is controversial and hasn't been totally decided on, I believe. We've still had many active discussions on this.
There was a problem hiding this comment.
You'd prefer this to be removed or qualified as not decided yet?
There was a problem hiding this comment.
I'd like to remove this until we have some wide agreement on how the PM group should operate. Right now there is no wide agreement there.
|
Thanks for the feedback @jbeda. I had a couple questions for you. I'll push another round of changes after you respond. |
| - mentor REVIEWERS and CONTRIBUTORS | ||
| - Benefits | ||
| - TBD: swag | ||
| - **MAINTAINER**: |
There was a problem hiding this comment.
I wonder if we could extract REVIEWER and APPROVER (and OWNERmaybe?) from the ladder, and still express their importance. These specifically are about sub-trees, while the rest (seem to be) about the whole repo. They are more like modifiers on MEMBER.
Would that help address the "too many rungs in the ladder" point some were making?
| API REVIEWER and APPROVER are called out specifically because the API is critical to the | ||
| identity of Kubernetes and is a horizontal area that crosses directories and SIGs. | ||
|
|
||
| - [**API REVIEWER**]: |
There was a problem hiding this comment.
Obviously, there's some overlap between this and the layers stuff. I think it's pretty unambiguous as-is that this means the public-facing "main" kube API much more than things like plugin APIs or package APIs.
| - **SIG Participant**: active in one or more areas of the project; wide | ||
| variety of roles are represented | ||
| - **SIG Lead**: SIG organizer | ||
| - **SIG PARTICIPANT**: active in one or more areas of the project; wide variety of roles are represented |
There was a problem hiding this comment.
I agree we could break these out to multiple docs. It would be easier to digest. What if we (after initial merge?) made a dir for governance, and separate docs for each topic?
| Kubernetes | ||
| - Use the above forums as the primary means of working, communicating, and collaborating, as opposed to | ||
| private emails and meetings | ||
| - If used, Google Docs should be made available to everyone on the project. Share them with at least the |
| - **MEMBER**: | ||
| - Requirements | ||
| - an active contributor for at least 3 months | ||
| - authored and/or reviewed at least 10 merged non-trivial PRs |
There was a problem hiding this comment.
- Does this apply to just the core kubernetes/kubernetes repo? Or contributions to any Kubernetes project repo that are non-trivial (test-infra, community, helm, ingress, etc)?
- Are PRs weighted more heavily than reviews, or are they weighted equally?
- Are there guidelines for what makes a PR "non-trivial", or is that up to the person nominating?
There was a problem hiding this comment.
@cblecker Thanks for taking a look.
As for which repos this would apply to, that's explicitly TBD.
PRs and reviews: As written, equally, though I could imagine weighing reviews more heavily in order to encourage more reviewers.
Non-trivial: I wanted to allow discretion. There are some people who have submitted more than a dozen PRs, but all just fix typos using an automated mechanism. Those clearly shouldn't count.
| - active enough to be assigned issues and/or PRs, and to be added to a github team | ||
| (a SIG, for example) for notification purposes | ||
| - has enabled [GitHub’s two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/) | ||
| - nominated by a REVIEWER, APPROVER, MAINTAINER, OWNER, or LEAD on kubernetes-dev@googlegroups.com, |
There was a problem hiding this comment.
How would a contributor go about asking for a nomination? Or should the contributor wait until their contributions go noticed?
There was a problem hiding this comment.
@cblecker How one gets nominated hasn't been figured out yet. I've been asking for someone to build a contributor metrics dashboard so that we could track candidates.
kubernetes-retired/contrib#1029
|
Responded to a bunch of comments. I'd really like to see this document broken out and streamlined for readability before it is merged. I also think we need to decide on the scope of which parts of kubernetes this applies to before we merge it. |
|
I don't feel strong on pre or post-merge fixes but @jbeda brings up some interesting issues that are worth addressing. |
|
I agree the final state can be broken up, but I think it's under so much debat eright now that moving it around will make it impossible to proceed. |
|
This is dead. Closing. |
Ref #277
Sync from Google doc 1/24/2017
https://docs.google.com/document/d/1UKfV4Rdqi8JcrDYOYw9epRcXY17P2FDc2MENkJjMcas/edit
Comments will continue to be taken on the doc for now.