WIP: Add first draft of CloudEvents review #509
Conversation
Signed-off-by: Josh Berkus <[email protected]>
jberkus
added
wg/governance
needs-liaison-approval
|
|
||
| The following aspects of governance are exemplary, and can be referenced as examples for other projects to copy: | ||
|
|
||
| * The [List of Implementations](https://github.com/cloudevents/spec/blob/main/docs/open-source.md) is a very useful resource, particularly for Specification projects |
There was a problem hiding this comment.
Can we use commit hashes in the links to the files in GitHub? The reviews are done using snapshots in the time.
| @@ -0,0 +1,210 @@ | |||
| # CloudEvents Governance Review | |||
|
|
|||
| What follows is a governance review and assessment for the _CloudEvents project. This review is carried out by members of the Governance Working Group of TAG Contributor Strategy. The review may have been done because of a change in maturity level for the project, at the request of the TOC, or as a request by the project itself. If requested by the project, the review will be provided to the project maintainers. Otherwise, the review will be submitted to the TOC for their follow-up. | |||
There was a problem hiding this comment.
| What follows is a governance review and assessment for the _CloudEvents project. This review is carried out by members of the Governance Working Group of TAG Contributor Strategy. The review may have been done because of a change in maturity level for the project, at the request of the TOC, or as a request by the project itself. If requested by the project, the review will be provided to the project maintainers. Otherwise, the review will be submitted to the TOC for their follow-up. | |
| What follows is a governance review and assessment for the _CloudEvents_ project. This review is carried out by members of the Governance Working Group of TAG Contributor Strategy. The review may have been done because of a change in maturity level for the project, at the request of the TOC, or as a request by the project itself. If requested by the project, the review will be provided to the project maintainers. Otherwise, the review will be submitted to the TOC for their follow-up. |
|
|
||
| **Admins**: There are four Admins, who are in charge of project administration, including permissions, ensuring regular operation, calling meetings, and similar functions. The Admins are the maintainers of the project by CNCF definition. | ||
|
|
||
| **(Voting) Members**: an amorphous, but well-tracked, group consisting of all regular participants in specifications meetings. These members vote on actual changes to the spec and the roadmap according to very detailed voting rules, including per-company vote limits. |
There was a problem hiding this comment.
| **(Voting) Members**: an amorphous, but well-tracked, group consisting of all regular participants in specifications meetings. These members vote on actual changes to the spec and the roadmap according to very detailed voting rules, including per-company vote limits. | |
| **(Voting) Members**: an amorphous, but well-tracked, group consisting of all regular participants in specifications meetings. If there is ever the need for a formal vote, then these members are the ones who have "voting rights". It is worth nothing though, for regular activity (such as approving changes to the specifications), any person in the community can comment, review and ask for changes to PRs. All open comments on PR need to be addressed prior to the PR merging. In this sense, any member of the community (voting member or not) has the ability to block a PR from being merged. It is only if there are irreconcilable differences of opinion that a formal vote will be taken. The goal is to achieve consensus. As a result, there have only been a handful for formal votes, due to a difference of opinion, during the entire lifetime of the project. |
There was a problem hiding this comment.
That's all good information, but it belongs in your governance docs, rather than in this review.
There was a problem hiding this comment.
| | Code of Conduct | Complete | Uses link to CNCF CoC | | | ||
| | Contributor Guide | Partial | [CONTRIBUTING](https://github.com/cloudevents/spec/blob/main/docs/CONTRIBUTING.md) | See discussion above | | ||
| | Contributor Ladder | Partial | [GOVERNANCE](https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md) | Several roles exist, but qualifications and advancement are not explained | | ||
| | Maintainer Lifecycle | Missing | | How to become, or retire, a Voting Member is not explained anywhere | |
There was a problem hiding this comment.
I think the #voting section in the GOVERNANCE.md file covers this. Is there something missing?
There was a problem hiding this comment.
Ah, ok. Can we move that section? It's in a wierd and non-obvious place. Putting it where you define voting members would be better.
There was a problem hiding this comment.
Not sure how to tweak it. Under the membership section we point to #voting (specifically on the "voting member" definition), we point to #voting in the Meetings section and the voting section immediate follows the PR section.
| | Maintainer List | Partial | [OWNERS](https://github.com/cloudevents/spec/blob/main/OWNERS), [Spreadsheet](https://docs.google.com/spreadsheets/d/1bw5s9sC2ggYyAiGJHEk7xm-q2KG6jyrfBy69ifkdmt0/edit?pli=1#gid=0) | See discussion above | | ||
| | Code of Conduct | Complete | Uses link to CNCF CoC | | | ||
| | Contributor Guide | Partial | [CONTRIBUTING](https://github.com/cloudevents/spec/blob/main/docs/CONTRIBUTING.md) | See discussion above | | ||
| | Contributor Ladder | Partial | [GOVERNANCE](https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md) | Several roles exist, but qualifications and advancement are not explained | |
There was a problem hiding this comment.
Can you elaborate on what might be missing from the #membership section of the GOVERNANCE.md doc?
| | Project Purpose | Complete | [README](https://github.com/cloudevents/spec) | | | ||
| | Maintainer List | Partial | [OWNERS](https://github.com/cloudevents/spec/blob/main/OWNERS), [Spreadsheet](https://docs.google.com/spreadsheets/d/1bw5s9sC2ggYyAiGJHEk7xm-q2KG6jyrfBy69ifkdmt0/edit?pli=1#gid=0) | See discussion above | | ||
| | Code of Conduct | Complete | Uses link to CNCF CoC | | | ||
| | Contributor Guide | Partial | [CONTRIBUTING](https://github.com/cloudevents/spec/blob/main/docs/CONTRIBUTING.md) | See discussion above | |
There was a problem hiding this comment.
Not sure what's missing here. See comments on the next two lines too.
| | Governance Area | Coverage | Documents | Finding Notes | | ||
| |:----------------|:--------:|:------:|:--------------| | ||
| | Project Purpose | Complete | [README](https://github.com/cloudevents/spec) | | | ||
| | Maintainer List | Partial | [OWNERS](https://github.com/cloudevents/spec/blob/main/OWNERS), [Spreadsheet](https://docs.google.com/spreadsheets/d/1bw5s9sC2ggYyAiGJHEk7xm-q2KG6jyrfBy69ifkdmt0/edit?pli=1#gid=0) | See discussion above | |
There was a problem hiding this comment.
I think a link to the #voting section in the GOVERNANCE.md doc should be added, but I'm not sure what's missing.
| | Maintainer Lifecycle | Missing | | How to become, or retire, a Voting Member is not explained anywhere | | ||
| | Decision-making | Complete | [GOVERNANCE](https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md), [SDK Governance](https://github.com/cloudevents/spec/blob/main/docs/SDK-GOVERNANCE.md) | Nonlinear, but explained in exacting detail | | ||
| | Code and Docs Ownership | Complete | [OWNERS](https://github.com/cloudevents/spec/blob/main/OWNERS), plus each repo | | | ||
| | Security Reporting and response | Missing | | A security team exists but is not documented | |
There was a problem hiding this comment.
the main README has a "Security Concerns" section with info on how to report security concerns. Is that not sufficient?
There was a problem hiding this comment.
Not according to CNCF standards, no. There needs to be a body that can handle confidential reports of undisclosed security holes. This probably isn't required for the specification (but security folks would need to decide that), but is definitely necessary for the SDKs.
There was a problem hiding this comment.
We've gone with the assumption that since the spec doesn't introduce any new security mechanisms (beyond whatever transport level security is already defined by other spec or tools), it's pretty much out of our concern. Meaning, any security issue raised wouldn't really be a CE issue - it would be on the transport security mechanism used. Additionally, we've had security reviews (on the spec and SDKs) and no one has expressed any concerns.
There was a problem hiding this comment.
@PushkarJ , @achetal01, @sublimino can one of your sign off on this? This is really a TAG-Security requirement.
There was a problem hiding this comment.
Additional context wrt to specs, if the spec is hosting community SDKs or reference implementations in the org level repo or project repos, discoverability of a security reporting mechanism needs to be discoverable and accessible. For OpenFeature, they were changed to be directed to a single security.md with a reporting policy described.
The intent of this was to ensure that if a researcher or reporter needed to report an issue, they didn't spend forever hunting for it. Commonly, the security.md file integrated with GitHub makes this process simpler (thanks to a lot of community work)
| | Decision-making | Complete | [GOVERNANCE](https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md), [SDK Governance](https://github.com/cloudevents/spec/blob/main/docs/SDK-GOVERNANCE.md) | Nonlinear, but explained in exacting detail | | ||
| | Code and Docs Ownership | Complete | [OWNERS](https://github.com/cloudevents/spec/blob/main/OWNERS), plus each repo | | | ||
| | Security Reporting and response | Missing | | A security team exists but is not documented | | ||
| | Communication and Meetings | Partial | [GOVERNANCE](https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md) | meeting process, no calendar. should link to SDK comms info | |
There was a problem hiding this comment.
The main README points to the CNCF calendar: https://www.cncf.io/calendar/ and we're listed on there.
Added some text to the main README telling people to check the README of each SDK for its comm stuff. I'd prefer not to duplicate it in the main repo to avoid it getting out of sync or requiring multiple PRs when things change.
There was a problem hiding this comment.
Some of the SDKs have meeting/comms info, but some don't.
There was a problem hiding this comment.
I just checked them all and they all seem to have a section like this: https://github.com/cloudevents/sdk-javascript#community which one do you think I missed?
There was a problem hiding this comment.
I think you've filled in the missing ones, I need to do a re-check and then I can update this.
|
CE edits are being made in this PR: cloudevents/spec#1224 |
| | SDK-Csharp | Partial | Complete | Partial | | | ||
| | SDK-Javascript | Partial | Complete | Partial | | | ||
| | SDK-Rust | Missing | Complete | Partial | No maintainers listed | | ||
| | SDK-Powershell | Missing | Missing | Partial | No maintainers, no meetings or channel | |
| | SDK-Java | Partial | Complete | Partial | Currently a WIP project | | ||
| | SDK-Csharp | Partial | Complete | Partial | | | ||
| | SDK-Javascript | Partial | Complete | Partial | | | ||
| | SDK-Rust | Missing | Complete | Partial | No maintainers listed | |
|
|
||
| #### Admins | ||
|
|
||
| The list of Admins is current, and appears well-balanced, with four admins representing four different organizations. However, admins are listed only by GH handle, with no affiliation, contact information, or history; listing full information on each admin would enhance transparency. The Admins were set up as roles-for-life, with only one change of admin since the project was founded in 2018. There are no defined processes for removing an admin for inactivity, nor any expectation that new Admins will be recruited. |
There was a problem hiding this comment.
We describe the process for add/removing admins in the #admins section of the GOVERNANCE.md doc.
Correct we don't remove admins due to inactivity since most of them are inactive per the definition of the role - and we like it that way. There really isn't much for them to do, aside from run the weekly calls, and that's normally done by just one of them - with another person being their usual backup (e.g. for vacations).
It's not so much "role for life" as it's just a very minimal role and people can ask to be added, or removed, whenever they want.
There was a problem hiding this comment.
Yes, but you already have the problem that an admin has effectively left the project without resigning as an admin. So there needs to be some documented way to handle that.
There was a problem hiding this comment.
there is, someone can open a PR to remove them: https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md#admins
|
|
||
| The list of Admins is current, and appears well-balanced, with four admins representing four different organizations. However, admins are listed only by GH handle, with no affiliation, contact information, or history; listing full information on each admin would enhance transparency. The Admins were set up as roles-for-life, with only one change of admin since the project was founded in 2018. There are no defined processes for removing an admin for inactivity, nor any expectation that new Admins will be recruited. | ||
|
|
||
| Since, at this time one of the four admins (Ken Owens) is no longer active in the project per Devstats and meeting tracking, it would benefit Cloud Events to document a full Admin lifecycle including recruitment, promotion, qualifications, and emeritus status. Documenting this and following it would help ensure that the project retains a continuously active leadership. |
There was a problem hiding this comment.
Perhaps we need some more text around this, but it's a bit misleading to call it "leadership" since they really only act after approval from the group. They're more like secretaries.
There was a problem hiding this comment.
That isn't clear from the documentation; on a reading from the docs the admins are treated as Maintainers. Who are the Maintainers, but the CNCF definition? Can we make that clear?
There was a problem hiding this comment.
https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md#admins
says:
Since the role of an 'Admin' is mainly administrative...
And there's also this text under the definition of admin:
Admins are Members of the group but have the ability to perform administrative actions on behalf of the group. For example, manage the website, github repos and moderate the meetings. Their actions should be done with the knowledge and consent of the group. They also have the ability to merge/close PRs, but only per the group's approval.
There was a problem hiding this comment.
So it's nice to think of the admins as servants of the voting members, but the admins actually have quite a bit of power over the project. As such, they need to have a clearly defined lifecycle, just like we require regular code projects to have a clearly defined lifecycle for their maintainers.
There was a problem hiding this comment.
I'm still confused. We define how admins can be added and removed - that's the lifecycle: https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md#admins It's not clear to me what's missing.
|
|
||
| #### Voting Members | ||
|
|
||
| In contrast to the admins, voting members are defined by their activity through participation in spec meetings, ensuring that the list of voting members is always relatively current. This makes it quite an easy route to get involved in the project, and prevents staleness. The list of voting members is tracked through a [spreadsheet](https://docs.google.com/spreadsheets/d/1bw5s9sC2ggYyAiGJHEk7xm-q2KG6jyrfBy69ifkdmt0/edit?pli=1#gid=0), which raises some issues around transparency and auditability (for example, who owns that spreadsheet?). Balance is ensured by voting rules which do not permit employees of the same company from voting more than once. |
There was a problem hiding this comment.
Our governance doc now says: An Admin will be responsible for updating the spreadsheet.
There was a problem hiding this comment.
Where's the spreadsheet stored? In whose account? The Projects staff can help you with putting it in a CNCF-owned account. We really don't want it to get deleted if someone changes jobs.
|
|
||
| #### SDK Maintainers | ||
|
|
||
| SDK maintainers are not current. See Subprojects above. |
There was a problem hiding this comment.
| Areas of potential future development include: | ||
|
|
||
| * Complete reorganization of governance documentation for clarity and completeness. | ||
| * Adoption of a full Admin lifecycle that encourages turnover. |
There was a problem hiding this comment.
Not sure we want to encourage turnover just for the sake of turnover.
There was a problem hiding this comment.
You already have turnover, but you haven't acknowledged it.
There was a problem hiding this comment.
But you seem to be asking for us to encourage it - I don't see value in that. It happens, yes. But why should we try to force it? We document how it CAN happen here: https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md#admins
There was a problem hiding this comment.
It's a good idea to encourage it, yes. Not only to people leave, they burn out as well. If you're not doing anything to recruit new admins, then you won't get any, and pretty soon you'll be exercising the line in the governance that says what to do when the last admin leaves.
There was a problem hiding this comment.
This one feels like a very subjective thing. We have a process that's working, no one is complaining, we have at least 3 admins to cover stuff.... I don't see an issue. Swapping in new folks "just because" could only make things worse because it means we'll get people who might not actually want to do it beyond the initial "fake" prestige they think it'll give them and they'll half-ass it. Then the entire process runs the risk of falling apart because the folks who really do want to do it have been pushed out.
|
|
||
| Language-specific Software Development Kits (SDKs) exist as subprojects of CloudEvents. These are largely autonomous of the main spec project in a governance sense. There is a [template for SDK governance](https://github.com/cloudevents/spec/blob/main/docs/SDK-GOVERNANCE.md) and other guidance docs, but SDK projects are largely left on their own after creation. This leads to some problems: | ||
|
|
||
| * Some SDKs have gone completely unmaintained |
There was a problem hiding this comment.
"has a maintainer".
There was a problem hiding this comment.
ah ok - I opened a PR for each SDK to align on common governance docs - see this PR for how the SDKs will now do it: cloudevents/spec#1226
| * Some SDKs have gone completely unmaintained | ||
| * There are no processes for SDK archiving or SDK Maintainer offboarding | ||
| * No SDK roles are defined other than "maintainer" | ||
| * Certification of SDKs is not up to date |
There was a problem hiding this comment.
Which certification are you referring to ?
There was a problem hiding this comment.
Compliance with versions of the spec. Several SDKs are not current.
There was a problem hiding this comment.
According to https://github.com/cloudevents/spec/blob/main/cloudevents/SDK.md#feature-support they all support v1.0 - which is sufficient since we're still in the v1.0.x track.
| * Certification of SDKs is not up to date | ||
| * SDK repos do not appear to have OWNERS files or other administrative automation | ||
| * It's impossible to tell if SDKs are well governed since they have no minutes or video of their monthly meetings | ||
| * There's no defined governance relationship between other bodies and the SDKs or between maintainers of different SDKs |
There was a problem hiding this comment.
Which "other bodies" are you thinking of?
Do we have to have a relationship across SDKs?
There was a problem hiding this comment.
Admins and voting members.
There was a problem hiding this comment.
Can you elaborate on what you're looking for beyond what in this section: https://github.com/cloudevents/spec/blob/main/docs/GOVERNANCE.md#membership
There was a problem hiding this comment.
You don't have to have a relationship, but if you don't you want to spell it out: "SDKs are completely autonomous from other groups." There's some practical considerations to declaring that though, and it might not be acceptable to the TOC. For example:
- how do SDKs get removed/archived because of abandonment?
- who verifies that SDKs comply with the spec?
- who handles security reports against SDKs?
There was a problem hiding this comment.
I've opened cloudevents/spec#1229 to address this.
These "spec" level changes to CE's governance docs are now merged. |
|
Can we close this now that CE is graduated? |
Resolves #478
Please find our first cut at a review of CloudEvents governance. There are a number of issues identified here, many of which are documentation issues, so this PR will remain WIP in order for the project to address them.
Attn: @duglin @cathyhongzhang @TheFoxAtWork @dzolotusky
@aliok @geekygirldawn
Doug, please let WG/Governance know how we can help Cloud Events resolve the identified issues.