Proposal: Contributor ladder - aka How can someone become a maintainer?

We’ve talked a lot about how people can contribute to this project, and I thought it might help if we clearly defined some specific roles along with how newer contributors can move up within the project.

Keep in mind that this proposal does not suggest any changes to any of the existing roles that people hold now. Existing maintainers would still be maintainers under this proposal. This is designed to make it easier for new people to gain additional responsibilities over time.

All of this is loosely based on a draft CNCF Contributor Ladder template with a bit of adaptation from the k8s membership process.

Community Member

Description: A community member participates in the community and contributes their time, thoughts, etc. Users are anonymous users of the project – once they stop being anonymous and participate, they become a community member.

  • Responsibilities:
    • Must follow the Code of Conduct
  • How users can get involved with the community:
    • Labeling issues
    • Bug Triaging
    • Participating in community calls
    • Participating in the forums

Contributor

Description: A contributor contributes directly to the project and adds value to it, making the maintainers’ lives easier. Contributions need not be code.

  • Responsibilities/Requirements include:
    • Following the project contributing guide
    • Following the Code of Conduct
  • Criteria:
    • Regularly submits PRs
    • Shows up at meetings
    • Answers questions

Reviewer

  • Responsibilities include:
    • Following the project contributing guide
    • Following the Code of Conduct
    • Reviewing and providing feedback on contributions from others
  • Requirements:
    • 5 pull requests
    • Agreement from 2 maintainers
  • Additional Privileges:
    • Membership in the GitHub org to allow requesting reviews / assigning issues
  • Criteria:
    • Experience as a contributor
    • Regularly submits PRs
    • Shows up at meetings
    • Answers questions

Approver

Description: An approver approves pull requests before they’re merged by maintainers.

  • Responsibilities/Requirements include:
    • Ensuring that contributions follow the contributing guide
    • Following the Code of Conduct
    • Reviewing and providing feedback on contributions from others in a timely manner
  • Requirements:
    • 20+ reviews on other people’s pull requests.
    • Agreement from 2 maintainers
  • Additional privileges
    • Has Github rights to approve (but not merge) pull requests
  • Criteria:
    • Experience as a contributor and as a reviewer

Maintainer

Description: A maintainer is a contributor with commit access who can merge pull requests from others. Maintainer roles may include community managers, project managers, release managers, and docs managers.

  • Responsibilities/Requirements include:
    • Merging pull requests in a timely manner
    • Ensuring that contributions follow the contributing guide
    • Helping new contributors
    • Following the Code of Conduct
  • Requirements:
    • Agreement from more than half of the existing maintainers
  • Additional privileges
    • Commit access to project repo(s)
  • Criteria
    • Experience as a review, approver, and contributor

Maintainer roles may also include non-code roles including:

  • Community Manager
  • Project Manager
  • Release Manager
  • Docs Manager
  • Etc.

(speaking only for myself as an individual)

One of the things I spend a fair bit of mental energy on at Amazon is our role guidelines. I think the purpose of the role guidelines within a company are similar for a more fluid organization. Participants want to know what’s required for the work role they have, and they want to know what is required to be recognized and given additional responsibility (along with the rewards for good work, like those that come from a promotion).

One of the things that I try to steer away from in role guidelines stewardship are prescriptive quantified numbers (like “20+ reviews on other people’s pull requests”) when it comes to collaborative and creative work. On one hand, distilling work evidence down to these measurable activities may reduce risk of bias in “meritocratic” recognition. But I have also seen such criteria used in a gaming fashion (as I have also seen “meritocratic” systems, in some cases, to be fair.)

One of the things that I find missing in this ladder is trust. I know I’m a broken record on this, but I think that trust is essential in every tool that we use in governance.

To compare to another system of governance, the Xen Project explicitly calls out the need for trust among those who have roles in the project. (note to self: I should suggest an update to remove gender biasing language in this governance!)

The numbers should be considered more of a guideline than a hard and fast rule, and we can tweak the language to reflect that.

We can remove the numbers, but I think it helps people understand expectations about when it might be appropriate to expect to move up the ladder and when they should start asking about moving up.

Keep in mind that it’s going to be hard for people outside of Amazon to understand what to expect, so the more information and guidance we can give them, the more likely we are to be able to build a community of contributors without losing them through frustration with unclear expectations.

Actually, the whole point of getting approval from x maintainers is all about trust. As a contributor, you need to have earned the trust of more than one maintainer to move up in the project. As you said, trust is critical, which is why we require approval from more than one maintainer, which prevents a single maintainer from approving a friend without that person building trust more broadly within the project.

This is exactly the reason that there are 2 criteria. You can’t game the numbers alone to move up the ladder. You also have to build enough trust with the maintainers to get them to vouch for you. And you aren’t going to get maintainers to vouch for you if you’ve been trying to game the numbers.

I think trust is a given if you’re actively taking part, contributing your time, and following the Code of Conduct.
@dawnfoster - regarding the suggested ladder:
Is the promotion process initiated by the maintainers (top-down) or by the contributors that wish to be acknowledged and receive more privileges in the project (bottom-up)?
Top-down would allow us to be more context-sensitive to the numbered threshold of the promotions. Whereas, bottom-up allows the contributor to control whether they are interested to be reviewed for promotion.

I think it should be both depending on the situation. A couple of examples:

  • someone has made a bunch of contributions across several areas of the project and no one maintainer has seen how much they’ve contributed - they should be able to nominate themselves.
  • a maintainer notices that someone has made a bunch of really great contributions, they should encourage the person to move up the ladder.

Ultimately, moving up the ladder involves more responsibility and more work, so the contributor will always need agree, since they may not want this additional responsibility.

1 Like

I would personally prefer something a lot more frugal on maintainer time and lighter in process. It feels like a lot of levels proposed would require a ton of governance and attention, and probably will cause maintainers to easily make mistakes such as “promoted someone to approver without 10 PRs”.

Because things like complying with COC are everybody’s must haves, I would prefer something closer to 3 levels of trust: everyone, maintainer (can merge other people’s PRs), and admin (makes releases, has keys). I also would trust any admin to bring in a maintainer without a committee, or even a majority decision.

The point is not to police the numbers. The point is that the existing maintainers get to decide when they trust someone enough to move them up the ladder. The maintainer time commitment is extremely minimal using this approach. Someone asks to move up, and 2 of the many existing maintainers need to spend a few minutes deciding whether they trust that person enough to give them more responsibility.

We can easily re-write the text so that numbers are merely guidelines to help people know when it might be time to move up.

This is designed to make it easier for new people to gain additional responsibilities over time.

Thank you for keeping this dialogue open and moving it forward! It’s exciting to see that there are many folks contributing today that are certainly proving their merit. I can’t wait to see progress toward making that a reality. (progress > perfection)

I also like that you’re thinking about “level of merit” required to earn “status”. To me this “have you paid your dues” discussion is always the most controversial because I think creating a subjective mental state machine (process) is often the side effect of our natural desire to seek quantification and classification in an organization. Conflicting mental models certainly causes the most discourse on the lucene & solr project (just look at “naming” discussions; lol). (FWIW, I agree that we shouldn’t slap hard requirements on committer status; it’s something we’ve consciously moved away from on lucene and I think it has positively created a more equitable community)

Speaking concretely, there are only two GitHub access levels that map to these roles:
triage - read & clone repository, manage issues and pull requests (including labeling and assigning reviewers)
write - everything in triage + push to the repository (e.g., merge PRs).

From that perspective it looks to me like Reviewer / Approver are the same thing from a GitHub access level and the defined responsibilities are then largely artificial (not implying they aren’t important, they’re just further defining a certain contributor’s hat). What I like about this is that it feels like it creates a cosmetic role for the “Managerial” type (I don’t want to bring implications based on that specific label; I just wasn’t sure what other word to use here) in an OpenSource process that is often largely driven by hands on developers. I also feel like it introduces better checks and balances by creating a voice for the contributor that thinks from the 100000 foot view and doesn’t live in the weeds of the implementation on a daily basis. What it doesn’t do, though, is it doesn’t create anything concretely enforceable or truly definitive between the reviewer and approver role; they’re essentially the same thing so without somehow concretely identifying a reviewer from an approver I’m not sure this will stand the test of time.

I think trust is a given if you’re actively taking part, contributing your time, and following the Code of Conduct.

+1 This is part of the merit system that I like about the “Apache Way” (although I know other foundations do the same). Usually folks that can’t be trusted don’t make it through the nomination process.

Is the promotion process initiated by the maintainers (top-down) or by the contributors that wish to be acknowledged and receive more privileges in the project (bottom-up)?

I prefer the process initiated by the maintainers through the nomination and voting system. The Apache guidelines are also a pretty good place to start.

We can easily re-write the text so that numbers are merely guidelines

+1

I particularly appreciated the number of member levels in the original suggestion. When you can only be “nobody” (because we’re all welcome to contribute at any time) or “maintainer” implying you’re on the hook for all sorts of things, that’s a big step to take. In a few other projects I have seen the GitHub “triage” access used to great advantage to allow regular contributors the access levels to triage and label issues and otherwise give support to the project without necessarily being committers. That also seems like a constructive way to grow community members who might be full maintainers one day.

1 Like

I’ve taken a pass at simplifying the proposal by combining reviewer / approver and incorporating some other changes as suggested in this thread. I also added an admin role, which was missing in the original proposal. How does this version look?

Community Member

Description: A community member participates in the community and contributes their time, thoughts, etc. Users are anonymous users of the project – once they stop being anonymous and participate, they become a community member.

  • Responsibilities:
    • Must follow the Code of Conduct
  • How users can get involved with the community:
    • Labeling issues
    • Bug Triaging
    • Participating in community calls
    • Participating in the forums

Contributor

Description: A contributor contributes directly to the project and adds value to it, making the maintainers’ lives easier. Contributions need not be code.

  • Responsibilities/Requirements include:
    • Following the project contributing guide
    • Following the Code of Conduct
  • Criteria:
    • Regularly submits PRs
    • Provides comments and feedback on issues and PRs from other contributors
    • Shows up at meetings
    • Answers questions

Approver

Description: An approver approves pull requests before they’re merged by maintainers. We all have unique skills and experiences, so when a person will be ready for this responsibility varies by contributor, but a rough guideline might be after submitting 20 PRs and providing feedback on 10 PRs from others.

  • Responsibilities/Requirements include:
    • Ensuring that contributions follow the contributing guide
    • Following the Code of Conduct
    • Reviewing and providing feedback on contributions from others in a timely manner
  • Requirements:
    • Agreement from 2 maintainers
  • Additional privileges
    • Has Github rights to approve (but not merge) pull requests in specific repositories
  • Criteria:
    • Experience as a contributor
    • Regularly submits PRs
    • Shows up at meetings
    • Answers questions

Maintainer

Description: A maintainer is a contributor with commit access who can merge pull requests from others. Maintainer roles may include community managers, project managers, release managers, and docs managers.

  • Responsibilities/Requirements include:
    • Merging pull requests in a timely manner
    • Ensuring that contributions follow the contributing guide
    • Helping new contributors
    • Following the Code of Conduct
  • Requirements:
  • Additional privileges
    • Commit access to one or more project repos.
  • Criteria
    • Proven experience as a contributor and approver
    • Shows up at meetings
    • Answers questions

Maintainer roles may also include non-code roles including:

  • Community Manager
  • Project Manager
  • Release Manager
  • Docs Manager
  • Etc.

Admin

Description: An admin has administrative responsibilities across the entire GitHub organization and can do things like cut releases.

  • Responsibilities/Requirements include:
    • Responsible for administration, infrastructure, and releases.
  • Requirements:
  • Additional privileges
    • Admin access to the GitHub organization and other infrastructure.
  • Criteria
    • Previous administration experience
    • Experience as a maintainer
    • Shows up at meetings
    • Answers questions

I can’t tell whether, for example, “Maintainer = all the responsibilities, requirements and privileges of an Approver + a bunch of other things”, or is it not quite a ladder like that?

That’s exactly right! As you move up the ladder, you can and would still do some of the things from previous rung. We can make that more explicit in the final version.

@dblock @nknize @searchymcsearchface I’ve incorporate the changes requested and answered questions, so I think this is ready to go.

However, given that we don’t have an existing governance model in place, I’m not sure who gets to make this decision, since it’s a project-wide change? Do we open it up to a vote from the maintainers? If so, are all of the maintainers listed in the OpenSearch MAINTAINERS and OpenSearch Dashboards MAINTAINERS files? Or does someone else make this decision?

2 Likes

@searchymcsearchface I was just watching a talk at KubeCon, and it has loads of tips about building a contributor pipeline and how the contributor ladder fits into that process.