Various governance clarifications #1994

jbeda · 2018-04-01T04:12:25Z

We talked about some of this during the Steering committee meetings. I don't think any of this should be controversial.

jbeda · 2018-04-01T04:14:36Z

/committee steering
/sig contributor-experience

cblecker · 2018-04-01T05:13:59Z

/cc

dankohn · 2018-04-01T05:18:22Z

governance.md

+
+All code projects use the [Apache Licence version 2.0](LICENSE). Documentation repositories should use the [Creative Commons License version 4.0](https://git.k8s.io/website/LICENSE).
+
+Note that "Kubernetes incubator" process has been documented in favor of the new guidelines.


s/documented/deprecated/

Good catch. Thanks!

smarterclayton · 2018-04-01T17:01:29Z

committee-steering/governance/README.md

+When introducing a SIG charter or modification of a charter the following process should be used:
+
+- Identify a small set of owners from the SIG to drive the changes.
+  Most typically this'll be the SIG chairs.


nit: this will

smarterclayton · 2018-04-01T17:02:22Z

One very minor wording thing, lgtm otherwise. Will wait for others to read though.

jbeda · 2018-04-01T20:06:57Z

Thanks for the review. Nits/typos fixed.

wking · 2018-04-01T20:47:20Z

committee-steering/governance/README.md

+- Identify a small set of owners from the SIG to drive the changes.
+  Most typically this will be the SIG chairs.
+- Work with the steering committee to gain approval.
+  This can simply be submitting a PR and sending mail to [[email protected]].


Nit: the Markdown spec defines an implicit link name shortcut (e.g. [[email protected]][]), but leaving the name brackets off entirely seems to be an extention. Are we targetting a specific Markdown flavor here?

@wking links are at the bottom of the doc (this line is on line 62)

links are at the bottom of the doc (this line is on line 62)

Right, and those are fine. But the syntax used in this line (withought the trailng []) isn't in the spec. It's the "completely omit" case from the Kramdown spec, but I don't know how portable it is to other Markdown engines.

I think this is fine. We do it elsewhere in the repo.

This is already used in this file and I was just following the pattern. If and when we start using the content with a markdown parser that doesn't respect this syntax we can look to fix it. As it is, this is part of the commonmark spec which github users (https://spec.commonmark.org/0.28/#shortcut-reference-link). But the state of "spec" in the markdown world is a disaster and I really don't want to have that argument.

cblecker · 2018-04-01T21:30:42Z

README.md


-A first step to contributing is to pick from the [list of kubernetes SIGs](sig-list.md).
+* **Committees** are named sets of people that are chartered to take on sensitive topics.
+  This group is encouraged to be as open as possible while achieving its mission.


Is it worth mentioning that while they are encouraged to be open, by the nature of the topics they discuss committees are permitted to have private communications as well?

Is it worth mentioning that while they are encouraged to be open, by the nature of the topics they discuss committees are permitted to have private communications as well?

I think "as possible" already suggests this, but more explicit wording would be fine too.

cblecker · 2018-04-01T21:34:08Z

README.md

+Kubernetes is a set of subprojects, each shepherded by a Special Interest Group (SIG).
+Most decision making in Kubernetes happens through SIGs.
+
+A SIG can have its own policy for contribution, described in a `README` or `CONTRIBUTING` file in the SIG folder in this repo (e.g. [sig-cli/CONTRIBUTING](sig-cli/CONTRIBUTING.md)), and its own mailing list, slack channel, etc.


The link goes to CONTRIBUTING.md but the text only says CONTRIBUTING.

cblecker · 2018-04-01T21:41:54Z

committee-steering/governance/README.md

+
+- Identify a small set of owners from the SIG to drive the changes.
+  Most typically this will be the SIG chairs.
+- Work with the steering committee to gain approval.


Wouldn't working with the steering to gain approval be a latter step in the process (after circulating changes with the sig and/or community)?

I was structuring this as an OARP type thing -- Owners, Approvers, Reviewers and Participants. I'll rework it so that it is viewed as more of a sequential process.

cblecker · 2018-04-01T21:44:59Z

committee-steering/governance/README.md

+- Identify a small set of owners from the SIG to drive the changes.
+  Most typically this will be the SIG chairs.
+- Work with the steering committee to gain approval.
+  This can simply be submitting a PR and sending mail to [[email protected]].


@wking links are at the bottom of the doc (this line is on line 62)

cblecker · 2018-04-01T21:45:33Z

governance.md

@@ -109,6 +110,8 @@ This is the purpose of Working Groups (WG). The intent is to make
 Working Groups relatively easy to create and to deprecate, once
 inactive.

+Working groups do not own any code or subprojects. Instead, they are a place for people to discuss topics that cross SIG boundaries.


nit: the rest of this doc is wrapped at 80 chars

I'm a fan of one sentence per line as it tends to merge and diff better. But I didn't want to modify content that wasn't changing and create extra diff noise.

cblecker · 2018-04-01T21:46:00Z

governance.md

-communication have yet to be formalized, but when in doubt, use
-[email protected] and make an announcement at the
-community meeting.
+The [KEP process] is being developed as a way to facilitate definition, agreement and communication of efforts that cross SIG boundaries.


nit: the rest of this doc is wrapped at 80 chars

bgrant0607 · 2018-04-02T16:30:37Z

See also #1986

pwittrock · 2018-04-02T16:45:34Z

README.md

+* **Committees** are named sets of people that are chartered to take on sensitive topics.
+  This group is encouraged to be as open as possible while achieving its mission.
+  Examples of committees include the steering committee and things like security or code of conduct.
+* **Special Interest Groups (SIGs)** are persistent open groups that focus on a part of the project.


what does it mean to be open in membership?

transparent?

what does it mean to be open in membership?

transparent?

An alternative interpretation would be that that self-nomination is sufficient to join (i.e. that there's no new-member vetting process). Perhaps the wording here (and/or in sig-governance.md?) could be updated to make it clear which of those is intended? Do non-lead SIG members have any explicit powers?

Right now in the steering committee we are working on guidance/process for the level of "membership" needed to participate in processes like voting for the steering committee. As part of that I don't want to overload the term "membership". I'll reword this to say that anyone is welcome to contribute and participate.

pwittrock · 2018-04-02T16:50:05Z

committee-steering/governance/README.md

+    - The steering committee will be looking to ensure the scope is reasonable (and within the scope of Kubernetes) and that processes are fair.
+- Alert the rest of the SIG in question to the changes so that anyone within the SIG can object.  
+  Including the SIG mailing list in communications with the steering committee would work for this.
+- For large changes alert the rest of the Kubernetes community as the scope of the changes becomes clear.


May also want to announce at the community meeting

pwittrock · 2018-04-02T17:02:00Z

committee-steering/governance/README.md

+When introducing a SIG charter or modification of a charter the following process should be used:
+
+- Identify a small set of owners from the SIG to drive the changes.
+  Most typically this will be the SIG chairs.


What is the process for a new SIG? Presumably it folks proposing the SIG agree upon the chairs / tech leads?

Unfortunately, this process is split between this doc and /sig-governance.md. We should probably rationalize these but that is a bigger change. Advice would be appreciated.

I did change that in this PR too to say that for creating a SIG a set of folks proposing the SIG should work with the Steering Committee to scope it.

pwittrock · 2018-04-02T17:02:40Z

committee-steering/governance/README.md

+  Most typically this will be the SIG chairs.
+- Work with the steering committee to gain approval.
+  This can simply be submitting a PR and sending mail to [[email protected]].
+  If more substantial changes are desired it is advisable to socialize those before drafting a PR.


I'd expect the SIG to have consensus before asking the SC to review the changes.

I'd expect the SIG to have consensus before asking the SC to review the changes.

Or to have deadlocked?

Reordered to make it more clear. (pushing soon).

pwittrock · 2018-04-02T17:03:20Z

Left a few minor comments. Otherwise LGTM.

bgrant0607 · 2018-04-03T06:11:35Z

README.md


-Kubernetes is a set of subprojects, each shepherded by a Special Interest Group (SIG).
+Kubernetes has three types of groups that are officially supported:


This omits subprojects.

https://github.com/kubernetes/community/blob/master/governance.md#community-groups

So -- I'm torn on this and would love advice. In my mind subprojects are a subunit of a SIG. They are scoped and live/die and are governed by the owning SIG. It is up to the SIG to decide how tightly those sub-projects are controlled and what the process for figuring out who has commit permissions on those.

I'm happy to rationalize this and either demote them to be sub-SIG in governance.md or add them here. Let me know what you prefer.

Opinion: because they are created and destroyed by the sigs, they should be at a sub-sig level.

Yes, but lack of awareness of subprojects leads to attempts to form WGs that should really be subprojects.

I would be fine with a mention under the SIG bullet rather than just below.

Part of the governance doc should be to communicate it. People often skim docs like this. If we can make it pop for a skimmer that subprojects are owned by SIGs that pop might be useful in communicating it.

idvoretskyi · 2018-04-03T15:46:34Z

/cc

bgrant0607 · 2018-04-04T00:15:01Z

README.md

+* **Special Interest Groups (SIGs)** are persistent open groups that focus on a part of the project.
+  SIGs must have open and transparent proceedings.
+  Anyone is welcome to participate and contribute provided they follow the Kubernetes Code of Conduct.
+  The purpose of a SIG is to own and develop a set of subprojects (defined below).


Please bold "subprojects"

I'm putting a subpoint under SIGs to call out subprojects. It'll be in the list but clearly "under" SIGs.

philips · 2018-04-06T18:57:33Z

LGTM

idvoretskyi · 2018-04-07T10:46:18Z

LGTM from me.

bgrant0607 · 2018-04-20T18:01:41Z

governance.md

+Working groups do not own any code or subprojects. Instead, they are a place for people to discuss topics that cross SIG boundaries.
+
+Working groups are primarily used to facilitate topics of discussion that are in scope for Kubernetes but that cross SIG lines.
+If a set of folks in the community want to get together and discuss a topic, they can do so without forming a Working Group.


It seems like this paragraph and the first paragraph should be merged or refactored.

I also want to clarify the "short-lived" aspect. We expect WGs to not live forever -- they should have a goal and concrete deliverables, but being short-lived shouldn't be a reason to create a WG. For example, a WG isn't needed for every short-term effort. Every release ships the results of many short-term efforts.

I also do want to address the class of SIGs/WGs for "use case X on Kubernetes": most of SIG Apps, SIG Big Data, M L WG, the proposed IoT/Edge WG. I will send email about that.

Most of our current WGs probably should not be WGs.

philips · 2018-07-13T21:50:29Z

@brendanburns and I had to answer questions regarding this stuff. Particularly the commitee, sig, and subproject thing. Can you rebase and merge this @jbeda ?

michelleN · 2018-09-26T19:49:13Z

@jbeda - these are really helpful changes. would you mind re-basing so we can merge?

Signed-off-by: Joe Beda <[email protected]>

jdumars · 2018-10-01T16:18:54Z

/lgtm

jdumars · 2018-10-01T16:19:20Z

Thank you Joe for getting this done!

philips

I am going to say we can fix my one comment at the same time #2702 is sorted.

Approving but holding for the rest of steering to have until Friday to review.

/approve
/hold

philips · 2018-10-02T16:43:06Z

governance.md

@@ -106,15 +107,28 @@ This is the purpose of Working Groups (WG). The intent is to make
 Working Groups relatively easy to create and to deprecate, once
 inactive.

-To propose a new working group, first find a SIG to sponsor the group. 
+Working groups do not own any code or subprojects. Instead, they are a place for


we kept getting hung up on this during the WG discussion. I think everyone agreed working groups can create and prototype. Just that the code landing in Kubernetes is contingent on SIG/subproject approval. "own any code" is confusing in this meaning.

Agreed. I think that this needs to be addressed further up in the doc too.

How about:

“Since WG are intended to have a definite lifetime, to prevent orphaned code at the dissolution of a WG all code in Kubernetes must have a SIG to own and maintain it. The sponsoring SIGs for a WG are expected to own and manage the code created for Kubernetes by a WG, and have authority on whether code created in a WG should become part of Kubernetes”

Or similar?

Perhaps a bit wordy, but otherwise fine. It can be word-smithed in a followup PR, IMO.

@philips @smarterclayton @quinton-hoole

We have a repository policy:
https://github.com/kubernetes/community/blob/master/github-management/kubernetes-repositories.md

This PR should not change it.

k8s-ci-robot · 2018-10-02T16:44:51Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: philips

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [philips]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

quinton-hoole

Agree with @philips that code development/ownership by WG's requires minor clarification to avoid wasting more time on that in discussions. Other than that, lets merge this ASAP and address the remaining nits in followup PR's.
LGTM.

quinton-hoole · 2018-10-02T19:24:44Z

governance.md

@@ -106,15 +107,28 @@ This is the purpose of Working Groups (WG). The intent is to make
 Working Groups relatively easy to create and to deprecate, once
 inactive.

-To propose a new working group, first find a SIG to sponsor the group. 
+Working groups do not own any code or subprojects. Instead, they are a place for


Agreed. I think that this needs to be addressed further up in the doc too.

quinton-hoole · 2018-10-02T19:26:21Z

README.md

+    These are smaller groups that can work independently.
+    Some subprojects will be part of the main Kubernetes deliverables while others will be more speculative and live in the `kubernetes-sigs` github org.
+* **Working Groups** are temporary groups that are formed to address issues that cross SIG boundaries.
+  Working groups do not own any code or other long term artifacts.


See @philips comment below. Clarify to make it clear that prototypes and proof-of-concept implementations by working groups are in scope and encouraged.

We have a repository policy:
https://github.com/kubernetes/community/blob/master/github-management/kubernetes-repositories.md

This should not change it.

quinton-hoole · 2018-10-02T19:33:02Z

governance.md

-SIGs must have at least one and ideally two SIG leads at any given
-time. SIG leads are intended to be organizers and facilitators,
+SIGs must have at least one and ideally two SIG chairs at any given
+time. SIG chairs are intended to be organizers and facilitators,


I think that having chairs from multiple companies/organizations should be very strongly encouraged, and that single-company groups of chairs should be the exception, and clearly justified when this is required for practical reasons.

quinton-hoole · 2018-10-02T19:35:13Z

governance.md

+highlight and encourage a larger ecosystem (with things like slack channels)
+without offering any official endorsement.
+
+To propose a new working group, first find a SIG to sponsor the group.


Given that WG's are intended to cross SIGs, I think that multiple sigs should sponsor. If only one SIG is in support of the WG, it can simply live in the SIG with all other discussions and/or sub-projects there.

brendanburns · 2018-10-03T15:32:57Z

Agree, we should just point at the repo policy here. "Like any other code related to kubernetes, any code created by a WG will be governed by the repo policy described here."

…

On Tue, Oct 2, 2018, 11:44 PM Brian Grant ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In governance.md <#1994 (comment)>: > @@ -106,15 +107,28 @@ This is the purpose of Working Groups (WG). The intent is to make Working Groups relatively easy to create and to deprecate, once inactive. -To propose a new working group, first find a SIG to sponsor the group. +Working groups do not own any code or subprojects. Instead, they are a place for @philips <https://github.com/philips> @smarterclayton <https://github.com/smarterclayton> @quinton-hoole <https://github.com/quinton-hoole> We have a repository policy: https://github.com/kubernetes/community/blob/master/github-management/kubernetes-repositories.md This PR should not change it. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1994 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABOYXls8Ee7Y9VSsREtqMZFw9qPqQI3Bks5uhFzbgaJpZM4TCtIS> .

philips · 2018-10-08T19:38:26Z

/hold cancel

philips · 2018-10-08T19:43:02Z

Filed #2766 in an effort to close out this 7 month old PR.

Thanks @jbeda and reviewers.

jbeda requested review from bgrant0607 and pwittrock April 1, 2018 04:12

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Apr 1, 2018

k8s-ci-robot requested a review from grodrigues3 April 1, 2018 04:12

k8s-ci-robot added committee/steering Denotes an issue or PR intended to be handled by the steering committee. sig/contributor-experience Categorizes an issue or PR as relevant to SIG Contributor Experience. labels Apr 1, 2018

k8s-ci-robot requested a review from cblecker April 1, 2018 05:14

dankohn reviewed Apr 1, 2018

View reviewed changes

smarterclayton reviewed Apr 1, 2018

View reviewed changes

jbeda force-pushed the sig-clarification branch from 01a8a86 to b3b4294 Compare April 1, 2018 20:06

wking reviewed Apr 1, 2018

View reviewed changes

cblecker reviewed Apr 1, 2018

View reviewed changes

pwittrock reviewed Apr 2, 2018

View reviewed changes

michelleN mentioned this pull request Apr 2, 2018

Include more instructions on WG creation. #1986

Merged

jbeda force-pushed the sig-clarification branch from b3b4294 to 0b97e13 Compare April 2, 2018 23:00

jbeda mentioned this pull request Apr 2, 2018

Rationalize governance.md, sig-governance.md and committee-steering/governance #1997

Closed

bgrant0607 reviewed Apr 3, 2018

View reviewed changes

k8s-ci-robot requested a review from idvoretskyi April 3, 2018 15:46

bgrant0607 reviewed Apr 4, 2018

View reviewed changes

parispittman mentioned this pull request Apr 6, 2018

Improve Documentation - What is a sig and what the sigs are #1976

Closed

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 15, 2018

bgrant0607 reviewed Apr 20, 2018

View reviewed changes

philips assigned jbeda Jul 13, 2018

bgrant0607 mentioned this pull request Sep 27, 2018

Clarify process for Working Group formation #2702

Merged

jbeda added 3 commits September 27, 2018 14:14

Add OARP approval process for SIG charters

f4d36b4

Signed-off-by: Joe Beda <[email protected]>

Connect dots around SIG governance

1cb83ad

Signed-off-by: Joe Beda <[email protected]>

Add more prominent details around SIGs/WG/Committees

2a04222

Signed-off-by: Joe Beda <[email protected]>

jbeda force-pushed the sig-clarification branch from 9d0ccf2 to 2a04222 Compare September 27, 2018 21:27

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 27, 2018

k8s-ci-robot assigned jdumars Oct 1, 2018

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 1, 2018

philips reviewed Oct 2, 2018

View reviewed changes

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Oct 2, 2018

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 2, 2018

quinton-hoole reviewed Oct 2, 2018

View reviewed changes

philips mentioned this pull request Oct 8, 2018

README: link to repository policy for working groups #2766

Closed

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Oct 8, 2018

k8s-ci-robot merged commit c0f27ee into kubernetes:master Oct 8, 2018

spiffxp mentioned this pull request Oct 18, 2018

Document what working groups are, and how to form and disband kubernetes/steering#27

Closed


		All code projects use the [Apache Licence version 2.0](LICENSE). Documentation repositories should use the [Creative Commons License version 4.0](https://git.k8s.io/website/LICENSE).

		Note that "Kubernetes incubator" process has been documented in favor of the new guidelines.


		Kubernetes is a set of subprojects, each shepherded by a Special Interest Group (SIG).
		Kubernetes has three types of groups that are officially supported:

Various governance clarifications #1994

Various governance clarifications #1994

Conversation

jbeda commented Apr 1, 2018

jbeda commented Apr 1, 2018 • edited Loading

cblecker commented Apr 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smarterclayton commented Apr 1, 2018

jbeda commented Apr 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Apr 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pwittrock commented Apr 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mattfarina Apr 4, 2018 • edited Loading

Choose a reason for hiding this comment

idvoretskyi commented Apr 3, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

philips commented Apr 6, 2018

idvoretskyi commented Apr 7, 2018

Choose a reason for hiding this comment

philips commented Jul 13, 2018

michelleN commented Sep 26, 2018 • edited Loading

jdumars commented Oct 1, 2018

jdumars commented Oct 1, 2018

philips left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

k8s-ci-robot commented Oct 2, 2018

quinton-hoole left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brendanburns commented Oct 3, 2018 via email

philips commented Oct 8, 2018

philips commented Oct 8, 2018

jbeda commented Apr 1, 2018 •

edited

Loading

mattfarina Apr 4, 2018 •

edited

Loading

michelleN commented Sep 26, 2018 •

edited

Loading