Contributors, Committers, and Maintainers + CODEOWNERS - What rules do we want to define for Hiero

[hendrikebbers]

I wrote down a definition on Contributors, Committers, and Maintainers groups + how all that works in combination with GitHub CODEOWNERS. Before brining it to the TSC I want to open an discussion on it.

In Hiero (as in LF), we now 3 different roles: Contributors, Committers, and Maintainers.

• A Contributor is a person who makes any contribution to the project (can be opening an issue). A Contributor has no specific rights on the org or repositories.
• If a Contributor makes a lot of good code contributions, a Committer or Maintainer can nominate him to become a Committer. No formal process for that. It can be an async discussion in any chat tool, a discussion in a meeting or just by creating a PR against https://github.com/hiero-ledger/governance/blob/main/config.yaml. All Maintainers should vote on that nomination. The vote should be held in a GitHub PR or discussion so that we have public record.
• A Committer has specific rights for a project (a repository). As defined here (https://github.com/hiero-ledger/governance/blob/main/config.yaml), every Committer has the rights determined by the WRITE GitHub role definition (see https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-[…]anaging-repository-roles/repository-roles-for-an-organization).
• As long as a Committer follows Hiero's Code of Conduct (https://github.com/hiero-ledger/.github/blob/main/CODE_OF_CONDUCT.md), I do not see a good reason why that person should lose the Committer rights. Maybe if a committer is not making good contributions anymore... let's say he/she is introducing a lot of breaking changes. In theory, we could remove people from that group after a long inactivity (1/2 year or 1 year?). A decision like that must come from the Maintainers of the project, who need to vote on it. We have not defined that so far, and I do not know if we can or if the Hiero Technical Steering Committee (TSC) can only suggest best practices here.
• Every project (repository) must have a list of Maintainers. For a small project like an SDK, 2-3 are good, but we should have more for larger projects (consensus-node). Maintainers have the rights defined by the MAINTAIN Github Role definition (see https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-[…]anaging-repository-roles/repository-roles-for-an-organization).
• A Committer can be nominated to become a Maintainer, and all Maintainers should vote on that. Here we should define what is the general bar that such nominatioin makes sense. Everything that applies to the Contributor->Committer process applies to the Committer->Maintainer process.
• While a Committer can create branches directly in the repository, assign issues, and review/merge PRs, a maintainer should drive the project's roadmap/vision and take care of topics like community meetings, the general structure of the project (fits our best practices, is secure, etc.), and so on. In addition, the Maintainers should report project updates to the Hiero TSC.
• It is not the goal that every Committer becomes a Maintainer, and having hundreds of Maintainers does not make sense. Based on that, I suggest that an inactive Maintainer is degraded to a Committer after some time of inactivity (again, 1/2 year is a minimum from my point of view). A decision like that must come from the Maintainers of the project, who need to vote on it. We have not defined that so far, and I do not know if we can or if the Hiero Technical Steering Committee (TSC) can only suggest best practices here.

A project can decide to support GitHub CODEOWNERS (see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). Since we officially have the Contributors, Committers, and Maintainers roles getting that together with GitHub CODEOWNERS is a little bit tricky. Roger and I worked on some best practices together with LF. Let me share the current state:

• The CODEOWNERS file defines some specific accounts (that can be organized in groups) that are owners of particular files (or folders) of a repository. We will name them Codeowners. A PR that contains changes on those files needs to be approved by one of those Codeowners.
• CODEOWNERS is a best practice. It should be encouraged in all projects (certainly not required). This helps maintainers ensure that the codebase is getting reviewed by the experts on those areas of the code. Should we define a suggestion for projects that have over x Committers/Maintainers?
• A GitHub CODEOWNERS file will not affect the definition of Contributors, Committers, and Maintainers.
• With that in mind, it makes zero sense that a person named a Codeowner in the CODEOWNERS file is not a Committer or Maintainer. Such a person would not be able to approve PRs in general.
• In a small project (that may have 10 Committers and Maintainers), the most straightforward approach would be to name the accounts directly in the CODEOWNERS file. By doing so, we have our groups (Contributors, Committers, and Maintainers) and a more fine-grained definition regarding Code ownership for the Committers and Maintainers.
• You do not want to name each account individually in the CODEOWNERS file for a large project like consensus-node. Therefore, we created groups for code ownership. Again all people in those groups should be Committer or Maintainer of the project. Otherwise it does not make any sense to add them.
• Today, we do not have a definition of who defines the CODEOWNERS file for a project. I would suggest that the Maintainer do this. This includes that we do not have rules when somebody is removed from a CODEOWNERS file.

[hendrikebbers]

LFDT has already defined some rules regarding "Becoming a Maintainer" and "Removing Maintainers". See https://lf-decentralized-trust.github.io/governance/governing-documents/SAMPLE-MAINTAINERS#removing-maintainers

[poulok]

@hendrikebbers, there is a conversation about some of this here regarding which maintainer vote on what.

[jwagantall]

yes, that conversation produced this new discussion so we can set the basis of what each of these definitions are....
I think the 2 conversations will now go hand in hand

[poulok]

Thank you @jwagantall for explaining. I will repeat my concern about the approach here, since this proposal seems the same as the proposal in the other conversation.

The various areas of expertise in the consensus node are highly specialized and separate. I think it is unrealistic to expect maintainers of Group A to vote on the promotion of someone to committer or maintainer of Group B. Yes, anyone can see if the contributions constitute clean code, but it is definitely note easy to determine if they are useful and follow the established design patterns, architecture, concurrency strategy, etc. Furthermore, counting such votes could give a false sense of security since most voters will cast votes that match the maintainers of Group B (in this example). It's better to just poll the maintainers of Group B.

[jwagantall]

@poulok , I think we need to discuss this in the next Community call. (If we can bring in this topic in the agenda that @hendrikebbers has)

My understanding is that the codeowners groups will come in handy for repos that are more fragile or require more reliable reviews.
In this case, if a person modifies a specific file, the right codeowners group should be added automatically as part of the requested reviewers.
Assuming the codeowners group include the people with the right expertise to review that part of the code, then we can get the right reviewer to approve or reject the PR.

Perhaps I am not understanding the side effect of the scenario? Would this not cover the issue in question:

"The CODEOWNERS file defines some specific accounts (that can be organized in groups) that are owners of particular files (or folders) of a repository. We will name them Codeowners. A PR that contains changes on those files needs to be approved by one of those Codeowners."

[poulok]

@jwagantall happy to discuss at the next community call.

My concern is not about reviewing and approving PRs. We have code owner groups for that which work well. My concern is who all is expected to vote on the promotion of a contributor to a committer, or a committer to a maintainer. It doesn't technically hurt to have more maintainers vote, but it seems like a waste of time for no benefit and we would be asking maintainers to cast a vote on something they do not have sufficient information to make good decision. Votes would be very close to a "rubber stamp" and no one should ever get in the habit of rubber stamping.

I think of the consensus node as multiple projects living together in a single repo. For the most part, each project operates fairly independently and most engineers do not cross project boundaries. Each project has it's own architecture, threading model, design constructs, etc. This is why we have specialized code owner groups, which is a good thing. We currently have multiple maintainer and committer groups as well, one for each project. My suggestion is to have the maintainers of each project vote on the promotion of engineers to their project group. We do not need to involve the maintainers from a different project. Only the maintainers of the group that the person is being promoted to vote.

[jwagantall]

I created a chart to help us visualize this better at
https://lucid.app/lucidspark/4b0150a8-8de6-4b8e-841d-c32b9ba8db3b/edit?viewport_loc=-824%2C-563%2C5562%2C2781%2C0_0&invitationId=inv_7339640f-a11a-4118-903b-e5252392ef26

[Nana-EC]

I agree with @poulok a starting point may be that the single group maintainers is an aggregated collection of the small maintainer groups to allow for all concerns to be covered.

[poulok]

@Nana-EC, I don't think such a group is useful. What role would this group fill that could not be done in a more effective an informed manner by the smaller groups?

[poulok]

@nana, please see this comment here if you have not already

[Nana-EC]

This was mainly to satisfy LFTDs need for a single group.
If an exception is possible then there's no need but if not then this would allow team flexibility in addition to adherence to the rule

[Nana-EC]

Okay, let me confirm previous context also. Thanks

[poulok]

I should clarify that I only speak in the context of the hiero-consensus-node.

[hendrikebbers]

We discussed the topic yesterday in the TSC since @Nana-EC was present. We will do a special solution for consensus node repo and I assume that we will invite to a meeting in near future to discuss the details.

[Nana-EC]

Correct.
Based on my experience on the SC team contributing in the CN repo I agree with @poulok view and in the meeting I think I highlighted more the impact on productivity and the PR approvals with the same context of expertize needed.
For that yes CODEOWNERES with fine consideration for folder structure should be sufficient.
It may also encourage some teams to reorganize and carve out their items in a way that allows for cleaner ownership e.g. Tests

[jwagantall]

@poulok @Nana-EC @hendrikebbers are we ok to close this discussion ? Given that we have already integrated these rules into our main governance repo and teams are allowed to post exceptions to those rules.

I want to keep the discussions cleared to be able to focus on new ones.

[poulok]

I agree, this discussion should be closed

[poulok]

@jwagantall are you able to close this discussion? If so, please do.