initiate a project Governance document

[fturib]

Why is this pull request needed and what does it do?

In order to graduate on last level inside CNCF organization, we need to clarify our GOVERNANCE rules.

Description

On advise of @caniszczyk , I started with a copy of the governance doc from fluentd, which, itself is extracted from Kubernetes' governance doc.
Then I tuned the text to adapt to CoreDNS project.

Please pay attention to these points:

1- MAINTAINERS are defined as the individuals assigned to the team 'maintainers' (from Github project). It is not the same as Reviewers or Approvers defined into OWNER.md

2- VOTE is defined by Organization + individual maintainers. This vote would be used to agree on a direction to the project. I am not sure, so far, it was used formerly. We may want to be able to have a 2/3 majority when it comes to vote. Which means a limited number of MAINTAINERS that are really focus on CoreDNS project. (as of today we have 2 Orgs + 2 individuals).

3- I made up the content of the paragraph "Projects". We may want to tune that description.

[corbot]

Thank you for your contribution. I've just checked the OWNERS files to find a suitable reviewer. This search was successful and I've asked superq (via /OWNERS) for a review.

If you have questions or suggestions for this bot, please file an issue against the miekg/dreck repository.

The bot understands the commands that are listed here.

[miekg]

[ Quoting <notifications@github.com> in "Re: [coredns/coredns] initiate a pr..." ]

Thank you for your contribution. I've just checked the *OWNERS* files to find a suitable reviewer. This search was successful and I've asked **superq** (via `/OWNERS`) for a review.

Good start. I think maintainers should be defined in the OWNERS file and then this triggles through (manually) to github teams and org. Upside here is that adding a maintainer is done via PR which gives it way more visibility. We don't track organization for any of the maintainers, so i'm not sure how we think that would work. What about unresponsive maintainers if we need a 3/4 vote for adding or removing maintainers?

[fturib]

I think maintainers should be defined in the OWNERS file and then this triggles
through (manually) to github teams and org. Upside here is that adding a
maintainer is done via PR which gives it way more visibility.

Yes, good idea. would need a PR and then the vote process with 2/3

We don't track organization for any of the maintainers, so i'm not sure how we
think that would work.

That is to ensure that one single org cannot take over the project. And also it ensures diversity in the votes.
eg as of today, Infoblox would have one vote, although have 2 maintainers. From the proposed doc. the first one the 2 that vote define the vote for the org.

What about unresponsive maintainers if we need a 3/4 vote for adding or
removing maintainers?

That is a good point ! (the threshold is 2/3). We need that each maintainer is really actively involved in the project. The vote is important and meaningful.
I guess there are several ways to ensure:

• have a difference between 'reviewer' and 'maintainers'. 2 different roles ? - and promote to maintainers only really active people on the project ? or have a limited number of seat ?
• have a description of responsibility of 'maintainer' as a voter. Have a way to move 'maintainers' out if not active ? a diplomatic way ... let say a list of 'emeritus maintainers' ?

[chrisohaver]

s/organization/organizations/

[fturib]

hum.. I will take the proposition of John. 'majority of organization vote acceptance'

[chrisohaver]

John suggested 'majority organization vote for acceptance'... which i think is more clear than 'majority of organization vote acceptance'

[chrisohaver]

This will create a lot of owners. Essentially all maintainers will also be owners?

[fturib]

I guess yes. And will be removed if no more maintainer.

[chrisohaver]

Use of "organization" is confusing here. This is presumably different than the maintainers' organizations we speak of in the prior section. Can we say "project" instead?

Maintainers will be added to the coredns GitHub project and added to the project's maintainers team.

Or, since adding to the maintainer team implies/requires adding to the project...

Maintainers will be added to the coredns GitHub project maintainers team.

[fturib]

I agree.

[miekg]

[ Quoting <notifications@github.com> in "Re: [coredns/coredns] initiate a pr..." ]

> We don't track organization for any of the maintainers, so i'm not sure how we > think that would work. That is to ensure that one single org cannot take over the project. And also it ensures diversity in the votes. eg as of today, Infoblox would have one vote, although have 2 maintainers. From the proposed doc. the first one the 2 that vote define the vote for the org.

Yes, but we currently have github handles that may or may not be connected to on org. Is that enough? Should we have an org field in the OWNERS?

> What about unresponsive maintainers if we need a 3/4 vote for adding or removing maintainers? That is a good point ! (the threshold is 2/3). We need that each maintainer is really actively involved in the project. The vote is important and meaningful. I guess there are several ways to ensure: - have a difference between 'reviewer' and 'maintainers'. 2 different roles ? - and promote to maintainers only really active people on the project ? or have a limited number of seat ? - have a description of responsibility of 'maintainer' as a voter. Have a way to move 'maintainers' out if not active ? a diplomatic way ... let say a list of 'emeritus maintainers' ?

I don't know. Maybe those are questions we can use our new maintainers@ list for?

[yongtang]

I think in the owners (or maintainers) file, the following format might help:

Assume A and B belongs to the same company or organization (so only one with *):

maintainers:
  - A *
  - B 
  - C *

[johnbelamaric]

I like it.

[johnbelamaric]

s/To apply a project as part of/To accept a project into/

[fturib]

make sense.

[johnbelamaric]

Receive a 2/3 majority organization vote for acceptance.

[fturib]

I take it.

[johnbelamaric]

change "on CoreDNS repository" to "on the coredns/coredns repository".

[johnbelamaric]

Add a link to the guidelines

[fturib]

I forgot the "below" -> "See repository guidelines, below"

[miekg]

[ Quoting <notifications@github.com> in "Re: [coredns/coredns] initiate a pr..." ]

I think in the owners (or maintainers) file, the following format might help: Assume A and B belongs to the same company or organization (so only one with `*`): ``` maintainers: - A * - B - C * ```

Yes, that's one way. But one org one vote (which is good in itself, assuming an org wants to take charge). But John and I both worked a Google (for about a week). You then have a situation where 2 independent people work for the same org (by coincidence). In that regard I rather stay independent (i.e. miek@miek.nl) so I don't loose my vote. Somewhere this things assume corporate entities are behind everyone. Anyway I like the initial doc. We should codify some things in the OWNERS file ( (add @<domain> for org ID or complete email addresses if people wish) and work out if the 2/3 voting will work in practice. /Miek

…

-- Miek Gieben

[yongtang]

I think working for a company but remain independent is a situation that makes sense. In CNCF, when sign up the CLA (https://github.com/cncf/cla), there is an option to either sign up as an individual, or as part of the corporation.

If the CLA is signed as corporation (or use corporate email for PR/issue/GitHub activity), then the maintainer will be considered as part of the entity, and the rule of "no two maintainer vote from the same entity" apply.

On the other hand, if the CLA is signed as an individual (and use individual email for PR/issue/GitHub activity), then the maintainer could be considered as independent. Thus not restricted by "no two maintainer vote from the same entity".

I don't think it is of a concern, though I think it makes sense to put a reasonable cap (say 2 or 3) on independent maintainers working for the same company. Maybe a FIFO rule? If 2 independent maintainers work for the same corporation, then the 3rd independent maintainer who work for the same company at the same time, will have to wait for one of the other maintainers to step down, to be able to vote.

[yongtang]

Software have life cycles and maintainers on any projects have as well. In the past Hadoop, OpenStack may have those as well. Though in order to avoid drama (saw that happen in some other open source communities), it might be better to specify what will trigger a removal. Ethnical or no contribution? May want to specify at least some criteria.

[stp-ip]

Also especially personal contributors might go into read-only mode for a bit due to other work taking priority, but come back more actively afterwards. Focusing on the full-time, corporate backed activity might result in personal contributors being considered inactive and push them out. But maybe that's a special case, but this always bugged me in other projects such as K8s.

[chrisohaver]

Focusing on the full-time, corporate backed activity might result in personal contributors being considered inactive and push them out.

It completely depends on how we define "active".... and how long in-activity is permitted. If the required activity level is very high, then corporate backed contributors get more voting power. If a very low level of activity is permitted, with long periods of complete in-activity, then individuals get more collective voting power.

As Yong says, I think we'll want to define more precisely what "contributing" means... but I assume it broadly means commits, code reviews, and or participation in meetings and issue discussions, relating to any repositories in the CoreDNS project. Also, we'll want to define required frequency of contributions to be considered active.

[fturib]

@yongtang : Looks like I misunderstood you comment above.
You request a change : can you be more specific on what text you would like to add or change or delete ?

Software have life cycles and maintainers on any projects have as well. In the past Hadoop, OpenStack may have those as well. Though in order to avoid drama (saw that happen in some other open source communities), it might be better to specify what will trigger a removal. Ethnical or no contribution? May want to specify at least some criteria.

[yongtang]

I think CoreDNS maintainers serve the bridges between community members. Reviewing PRs (with Code of Conduct) is the best bridge for the community.

## Expectations of Maintainers

Maintainers are the bridges between members of the CoreDNS community. Maintainers
actively participate in PR reviews. Maintainers are expected to respond to
assigned PRs in a reasonable time frame, either providing insights, or assign the
PRs to other maintainers.

## Changes in Maintainership

Maintainers who fail to meet the principles of CoreDNS community can be removed
by a 2/3 majority organization vote.

[codecov-io]

Codecov Report

Merging #2112 into master will decrease coverage by 0.05%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #2112      +/-   ##
==========================================
- Coverage   55.86%   55.81%   -0.06%     
==========================================
  Files         203      203              
  Lines        9991     9991              
==========================================
- Hits         5581     5576       -5     
- Misses       3987     3990       +3     
- Partials      423      425       +2

Impacted Files	Coverage Δ
plugin/proxy/lookup.go	71.66% <0%> (-3.34%)	⬇️
plugin/route53/route53.go	82.4% <0%> (-2.78%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d9efa96...94cb50d. Read the comment docs.

[fturib]

I udpated with easy fix comments.
But the workflow about maintainers is not resolved yet.

[fturib]

I remove all below proposition to be clear that it is no more on the table (at least not from me).

for MAINTAINERS, looks like we may need here to be more clear on the process, and have a way to step-up and step-down for the MAINTAINERS that avoid friction whenever possible. Which means knowing in advance the responsibilities and the rules to keep a good list of active MAINTAINERS

## MAINTAINERS change triggered by PRs and votes
There is a specific file MAINTAINERS.md that we need to modify each time there is a change in the list of maintainers. Most likely there will need a vote for approval before merging.

## MAINTAINERS responsibilities
* participate to the votes. On each call to vote, the MAINTAINER cannot remain silent. It either vote YES, either vote NO, either provide a comment for no decision. A vote is open for 2 weeks, unless it reaches an agreement before that delay.

* have a significant involvement in the project, measured by 'activity'.

## NEW MAINTAINERS
- Any reviewer that have the required level activity, that make the request can be elected as MAINTAINERS if it get the needed 2/3 vote of existing maintainers
- a former MAINTAINER can also asked to re-added to the list with the same process as for a reviewer

## STEPPING DOWN MAINTAINER
- Volunteering (no more personal time to involve in the project). Need a PR, but no need for vote.
- After an evaluation of activity, Maintainers below the level are automatically proposed for removing from maintainers. Need vote. And vote can be refused if other maintainer wills it after the failing maintainers is providing explanations.
- specific divergence in directions in the project. Need vote.

Whatever the reason, a former maintainer is always part of the list of 'emeritus maintainers'.
However he is removed from the Gihub 'maintainers' list, and lost its 'owner' privilege on the github project.

## MEASURING ACTIVITY
- Voting : it is important that every MAINTAINERS participate actively to the votes.
=> MAINTAINERS should not miss more than 2 votes in a row (or 2 votes since last evaluation of activity ?)
- Project activity: I guess we can get an easy measure from Github stats (need to be easy to collect and neutral statistic). We need an average of XX events per month.

NOTE: for instance, k8s just provided a minimum of 50 event of activity on the repo during the last year to have the right to vote for the steering committee.
## TRIGGERING EVALUATION OF ACTIVITY
- by default evaluation happen every 3 months.
- an evaluation should be trigger when we do not reach to get enough total votes. When a PR with vote as not enough feedback to take a decision.

NOTE: Change in measuring activity and decisions can still be made, using a PR with vote on the "GOVERNANCE.md" file.

[miekg]

[ Quoting <notifications@github.com> in "Re: [coredns/coredns] initiate a pr..." ]

+Maintainers can be removed by a 2/3 majority organization vote. Also especially personal contributors might go into read-only mode for a bit due to other work taking priority, but come back more actively afterwards. Focusing on the full-time, corporate backed activity might result in personal contributors being considered inactive and push them out. But maybe that's a special case, but this always bugged me in other projects such as K8s.

+1 I think we should have the governance to allow for this mode.

[chrisohaver]

We should also have a timeout. I think we need to define what is "active" but also for how long a person can be inactive before being voted out. Even if we say 1 contribution per month to be considered active, without at a timeout one rough month can get you ejected. Life happens.

Also, how would organization's activity/timeout be counted? Per individual or as a group?
I imagine that since there is a 1 vote limit for an organization, the activity would be tracked as a group. That is, if we implement a "1 contribution per month" requirement for activity, and there is a organization contributing with 3 members, then only 1 contribution per month from that organization is required to keep all members active (not 1 from each member).

[fturib]

+1 I think we should have the governance to allow for this mode.

That mean we allow a mode when a MAINTAINERS declare himself "on-hold" or "read-only". He is for a temp time out of the MAINTAINERS (I mean, we do not count on him for votes and do not care its activity during that time) but can comeback as active MAINTAINER when he wish w/o a vote.

There should be a max delay for the "read-only" mode - let say 6 months.

[yongtang]

I think there are separate issues here:

1. Keep the status of Maintainer.
2. Keep the voting right as part of the Maintainer.

As far as I know, CoreDNS is a open source project, not an corporate product. So it is hard to imagine CoreDNS project will be running like inside a company with any KPI metric nonsense.

Many people comes here to contribute in their FREE time, not collecting any paycheck. I just don't think it makes much sense to require people spending their FREE time (without collecting paycheck) to be so involved, are forced to be evaluated in a short interval every 3 month?

Unlike corporate, if you push people out, they may not like to come back. Remember there are so many open source projects and people certainly could work on other projects.

I am fine if a maintainer is not active then he or she does not have the right to vote for a period. If it is too long, say a year or so, yes everything is on the table.

But I just don't think it makes sense to require people to devote their FREE time to be evaluated every several months. Are we making CoreDNS project a corporate project?

[fturib]

Hi @yongtang. Thanks for the feedback.
I do not want to push CoreDNS in as a corporate project !.
And i agree that this activity measure is both not welcoming, neither easy to setup.
I would rather keep simple, have each maintainer inform themselves when 'read-only' or step down if not anymore interested by the project.

However, initially the point was to ensure we have MAINTAINERS that keep active, on the vote side, because we need 2/3 for important votes.

How about:

having an anniversary date where each year the MAINTAINERS need to declare themselves as still active on the project ?
The one that did not vote during the year could just step down by themselves .. or after a talk with other maintainers of the project.

It would be more 'positive' way.

[yongtang]

My understanding of the maintainer/committer of CoreDNS project is: a person who is able to help maintaining open source CoreDNS project in technical aspect: review, evaluate, and merge pull requests. That is the most important thing a maintainer should be involved.

[yongtang]

I hope CoreDNS remains an open source project with a focus on technical side.

[caniszczyk]

A maintainer should be anyone listed in a MAINTAINERS/OWNERS file

On Wed, Sep 26, 2018 at 8:01 PM Yong Tang ***@***.***> wrote: I hope CoreDNS remains an open source project with a focus on technical side. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2112 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAD5IWQK-_hoY159YbnM79LgjyGPEFBRks5ufCNQgaJpZM4WyZJv> .

-- Cheers, Chris Aniszczyk http://aniszczyk.org +1 512 961 6719

[fturib]

I updated the document, following most of the comments ..

• individuals declare if they contribute for an organization/company or as un-affiliated

• integrate an "Expectation from Maintainers"

• adapt Maintainership

• make OWNER the main source of list of Maintainers

• removed the automatic move to "owner" of Github project

• OWNER : added a begin of list of maintainers - based on current list in the 'maintainers' team of Github (2 organization, 2 individuals)
  Here, @miekg : can you say what is the full list of maintainers ? and verify the format I used is conform with maybe an automated process of the OWNER document. Thanks!

[miekg]

[ Quoting <notifications@github.com> in "Re: [coredns/coredns] initiate a pr..." ]

I updated the document, following most of the comments .. - individuals declare if they contribute for an organization/company or as un-affiliated

This can, and should be nothing more than providing an email in the OWNERS file (the top-level one). Possible as a `*@example.org` if you don't want your email there, but do want to show where you work. The domain part is taken as the "organization".

- integrate an "Expectation from Maintainers"

I like the "every one carries water" the k8s uses. I have to read the doc again. The removal of someone if a thorny item. Possibly this can be solved easily if someone reaches out via email to ask what is the matter.

- adapt Maintainership - make OWNER the main source of list of Maintainers - removed the automatic move to "owner" of Github project Here, @miekg : can you say what is the full list of maintainers ? and verify the format I used is conform with maybe an automated process of the OWNER document. Thanks!

I'll have to re-read. /Miek

…

-- Miek Gieben

[fturib]

The removal of someone if a thorny item. Possibly this can be solved easily if
someone reaches out via email to ask what is the matter.

@miekg , There is already a thread going on on mailing list maintainers@coredns.io ... do you receive it ?

[miekg]

Haha lol. Think I forgot to add myself.

…

On Fri, 28 Sep 2018, 14:28 Francois Tur, ***@***.***> wrote: The removal of someone if a thorny item. Possibly this can be solved easily if someone reaches out via email to ask what is the matter. @miekg <https://github.com/miekg> , There is already a thread going on on mailing list ***@***.*** ... do you receive it ? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2112 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAVkW1wsuN5D06gPsMzjT5gRrRYcxjUDks5ufiPfgaJpZM4WyZJv> .

[fturib]

Closing as too much change.
Created a new PR #2203 with the last version from Miek's proposition + decision making process defined