Update graduation_criteria.md #1033
Conversation
There have been some issues in CNCF where projects have waited too long to define basic governance processes, which have led to issues down the road as a project has scaled. It's better to encourage a project to start out with a simple governance structure in the beginning and evolve that over time versus starting with nothing and dealing with the aftermath of managing governance and growth at the same time. There are also great resources and templates now that folks can lean on to craft their own governance https://contribute.cncf.io/maintainers/governance Signed-off-by: Chris Aniszczyk <caniszczyk@gmail.com>
|
💯 👍🏾 |
|
@jberkus FYI |
There was a problem hiding this comment.
@caniszczyk Thank you for submitting this. @cncf/cncf-toc Please take a look, merging this PR will add an additional check to sandbox applications. @amye when this is merged in, we'll need to change the sandbox form to include this as a field to capture information.
| @@ -14,6 +14,7 @@ To be accepted in the sandbox a project must | |||
| * Adopt the CNCF [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) | |||
| * Adhere to CNCF [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) (including trademark transferred) | |||
| * List their sandbox status prominently on website/readme | |||
| * Explicitly define a project governance and committer process. The committer process should cover the full committer lifecycle including onboarding and offboarding or emeritus criteria. This preferably is laid out in a GOVERNANCE.md file and references an OWNERS.md or MAINTAINERS.md file showing the current and emeritus committers. See https://contribute.cncf.io/maintainers/governance/ for more info. | |||
There was a problem hiding this comment.
I'd add "preferably machine parsable markdown", but it does not need to be here in this file, we can add that somewhere under https://contribute.cncf.io/maintainers/governance/
There was a problem hiding this comment.
We have these terminologies: committer, maintainer, owner, etc. If there is no other place that clearly defines them, it is better to define them somewhere (could be in another place to which this file can reference)
There was a problem hiding this comment.
@cathyhongzhang seems like our FAQs could use an update to include those but we should keep that separate for now as we've not had them articulated before and would want them to align with the language used on contribute.cncf.io and other LF materials.
There was a problem hiding this comment.
@TheFoxAtWork Agree. We need to articulate them clearly and be consistent across CNCF
There was a problem hiding this comment.
I can reach out to TAG Contributor Strategy to see what they already have and figure out updates to our FAQs outside of this PR. CC @jberkus @CathPag @geekygirldawn
There was a problem hiding this comment.
TAG CS now has the first version of the non-technical glossary: https://contribute.cncf.io/resources/glossary/#project-maintainer.
There was a problem hiding this comment.
In CNCF, term “maintainer” is used over other similar terms such as “committer”.
But not necessarily in CNCF projects. I don't think it is the intention of the TOC to make projects use a standard noun. If it is the intention — that it be part of the 'light' oversight that projects are subject to — then it should be very clearly communicated.
There was a problem hiding this comment.
Thanks for the feedback @craigbox
I would be very happy to update the non-technical glossary with the outcome of this discussion (or a separate discussion).
There was a problem hiding this comment.
Raised an issue against the Glossary about this.
There was a problem hiding this comment.
I will echo what @craigbox says here: when projects sign up to join the CNCF they are assured that they won't be required to adopt a standard governance model. As a consequence, they have no expectation that they will be required to adopt some standardized language within their existing governance documentation
| * Have a healthy number of committers. A committer is defined as someone with the commit bit; i.e., someone who can accept contributions to some or all of the project. | ||
| * Explicitly define the criteria, process and offboarding or emeritus conditions for project committers/maintainers; or those who may interact with the CNCF on behalf of the project. The list of maintainers should be preferably be stored in a MAINTAINERS.md file and audited at a minimum of an annual cadence. |
There was a problem hiding this comment.
Is there a good reason not to upgrade the existence and review of MAINTAINERS.md from "should" to "must"?
There was a problem hiding this comment.
Please don't apply "must" to the file format. Istio keeps its list in yaml format as it is an input to peribolos.
| @@ -14,6 +14,7 @@ To be accepted in the sandbox a project must | |||
| * Adopt the CNCF [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) | |||
| * Adhere to CNCF [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) (including trademark transferred) | |||
| * List their sandbox status prominently on website/readme | |||
| * Explicitly define a project governance and committer process. The committer process should cover the full committer lifecycle including onboarding and offboarding or emeritus criteria. This preferably is laid out in a GOVERNANCE.md file and references an OWNERS.md or MAINTAINERS.md file showing the current and emeritus committers. See https://contribute.cncf.io/maintainers/governance/ for more info. | |||
There was a problem hiding this comment.
| * Explicitly define a project governance and committer process. The committer process should cover the full committer lifecycle including onboarding and offboarding or emeritus criteria. This preferably is laid out in a GOVERNANCE.md file and references an OWNERS.md or MAINTAINERS.md file showing the current and emeritus committers. See https://contribute.cncf.io/maintainers/governance/ for more info. | |
| * Explicitly define a project governance and maintainer selection process. The maintainer process should cover the full maintainer lifecycle including onboarding and offboarding or emeritus criteria. This preferably is laid out in a GOVERNANCE.md file and references an OWNERS.md or MAINTAINERS.md file showing the current and emeritus maintainer. See https://contribute.cncf.io/maintainers/governance/ for more info. |
Please stop using the word "committer". It is misleading and confusing to projects.
There was a problem hiding this comment.
And yet, the CNCF uses the word "committer" in the charter, and it's also the word used in several project's governance documentation. I would vote explicitly for using both terms here.
There was a problem hiding this comment.
Yeah, I'm trying to scrub it everywhere I see it. And we should amend the charter to remove it.
There was a problem hiding this comment.
I defer to your experience here Josh, but I don't understand the motivation - could you share more please? Is this a personal request, or to align with some broader industry change I was not aware of?
There was a problem hiding this comment.
Because, if you use git, every single contributor is a committer. Look at the "committer" stats in DevStats, the official metrics for CNCF projects. They include everyone with a merged PR.
So, for any potential contributor who's been in OSS less than 10 years, using the word "committer" to refer to project leadership is profoundly confusing. It's the equivalent of describing a retail business, and using the word "associates" as being the same as "management". So, yes, it's an industry change. Every time a TOC member says "committer" they sound 60 years old.
In addition to this, many/most CNCF projects have people who review and approve PRs who are not otherwise project leadership -- and people who are project leadership who don't do much approving PRs.
And, further, all of the documentation from CNCF staff, including all of the mailing lists, etc., refer to "maintainers". Having a single, clear term, which doesn't mean two radically different things is much better for everyone.
There was a problem hiding this comment.
Every time a TOC member says "committer" they sound 60 years old.
This ageist comment has no place in a CNCF discussion.
It feels to me like you've made this point about changing "committer" to "maintainer" over and over, but there's no evidence of a groundswell of support. I will keep making the point that we do not define governance, so projects can use whatever terminology suits them best. The language of the Charter uses the word "committer", and changing this needs a Governing Board discussion, so unless someone from the TOC and/or GB want to take it up, going round in circles on this doesn't seem like a great use of time.
There was a problem hiding this comment.
I echo Liz's sentiment about the 60 year old comment here.
The comment could imply that there is a requirement for a TOC member to be under 60 years old.
| @@ -14,6 +14,7 @@ To be accepted in the sandbox a project must | |||
| * Adopt the CNCF [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) | |||
| * Adhere to CNCF [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) (including trademark transferred) | |||
| * List their sandbox status prominently on website/readme | |||
| * Explicitly define a project governance and committer process. The committer process should cover the full committer lifecycle including onboarding and offboarding or emeritus criteria. This preferably is laid out in a GOVERNANCE.md file and references an OWNERS.md or MAINTAINERS.md file showing the current and emeritus committers. See https://contribute.cncf.io/maintainers/governance/ for more info. | |||
There was a problem hiding this comment.
I'm also going to suggest that an OWNERS file is not a substitute for MAINTAINERS.md. This is because the owners file contains ONLY github handles, and not contact information, affiliation, full name, or any other information about the maintainer. If the goal is to make the project more transparent to the TOC and potential contributors, then we need a full maintainers file.
There was a problem hiding this comment.
Although: the combination of a README with the extra information together with an OWNERS file works. It might be better to define what information needs to be exposed about maintainers.
There was a problem hiding this comment.
It is currently defined: it needs to show who the current and emeritus committers are. We don't need to determine exactly what is and isn't required or how the information is presented - when assessing a project, the TOC can simply look at the file and consider whether information about committers is present
This drive towards consistency across projects feels like a slippery slope towards yet more make-work process requiring busy project maintainers to re-write files to fit some arbitrary format. How does consistency between projects really help people who want to contribute to a project? Most folks concentrate on one thing at a time.
| * Have a healthy number of committers. A committer is defined as someone with the commit bit; i.e., someone who can accept contributions to some or all of the project. | ||
| * Explicitly define the criteria, process and offboarding or emeritus conditions for project committers/maintainers; or those who may interact with the CNCF on behalf of the project. The list of maintainers should be preferably be stored in a MAINTAINERS.md file and audited at a minimum of an annual cadence. |
There was a problem hiding this comment.
| * Explicitly define the criteria, process and offboarding or emeritus conditions for project committers/maintainers; or those who may interact with the CNCF on behalf of the project. The list of maintainers should be preferably be stored in a MAINTAINERS.md file and audited at a minimum of an annual cadence. | |
| * Explicitly define the criteria, process and offboarding or emeritus conditions for project maintainers; or those who may interact with the CNCF on behalf of the project. The list of maintainers should be preferably be stored in a MAINTAINERS.md file and audited at a minimum of an annual cadence. |
Still removing the word "committers".
There was a problem hiding this comment.
See above, we use the word "committers" in the charter so it seems strange to erase it here
| @@ -39,7 +40,5 @@ To graduate from sandbox or incubating status, or for a new project to join as a | |||
| * Have committers from at least two organizations. | |||
| * Have achieved and maintained a Core Infrastructure Initiative [Best Practices Badge](https://bestpractices.coreinfrastructure.org/). | |||
| * Have completed an independent and third party security audit with results published of similar scope and quality as the following example (including critical vulnerabilities addressed): https://github.com/envoyproxy/envoy#security-audit and all critical vulnerabilities need to be addressed before graduation. | |||
| * Explicitly define a project governance and committer process. The committer process should cover the full committer lifecycle including onboarding and offboarding or emeritus criteria. This preferably is laid out in a GOVERNANCE.md file and references an OWNERS.md file showing the current and emeritus committers. | |||
There was a problem hiding this comment.
OK, we don't want to just remove this without replacing it. By the time a project has gotten to graduation, they should have evolved (and, for that matter, used) their governance. That is, the expectations for transparency, accessibility, and completeness for a graduated project should be higher than they were for sandbox, and we should call that out as a requirement.
Draft text:
Have complete and detailed governance, both in documentation and in practice, that address all aspects of managing the project, including contributor roles, maintainer selection and departure, handling code of conduct and security incidents, and management of any subprojects. This governance should be open to all contributors and non-prejudicial towards any contributor affiliation.
There was a problem hiding this comment.
Also, question: if we're requiring governance at sandbox entry, what are we requiring at Incubation?
|
We should also suggest specific templates for "minimal governance". Would it be sufficient to simply link to the Maintainer Council template? Or do we want something even simpler than that? |
|
While it's great to have sample governance models and templates for projects to look at, there are projects that join the CNCF as established, successful, open, widely-adopted projects, with existing governance models that have served them well for years. We promise them that we will treat them with a light touch, so let's make sure that in trying to provide guidance to new and less-established projects, we don't turn that into additional requirements and extra work for these maintainers. |
|
As a result of today's TOC meeting, let's hold off on merging this PR. The recommendations from the task force will likely alter the criteria from what is recommended here. Once the recommendations from the task force are finalized and public comment is complete, we can determine if this PR is overcome by those recommendations |
|
Closing this PR as this consideration was added into the recent matriculation process changes and recommendations from the task force. |
There have been some issues in CNCF where projects have waited too long to define basic governance processes, which have led to issues down the road as a project has scaled. It's better to encourage a project to start out with a simple governance structure in the beginning and evolve that over time versus starting with nothing and dealing with the aftermath of managing governance and growth at the same time.
There are also great resources and templates now that folks can lean on to craft their own governance https://contribute.cncf.io/maintainers/governance