New Contributor Guide and Maintenance Setup

[derberg]

What we want to propose is not something new in the open-source realm. Every project at scale has, at some point, faced issues that we are currently encountering on the website - gaining popularity and a large number of contributors, which means:

• a huge number of pull requests
• a huge number of issues

New Contributor Guide

To be completely honest, there is not much new there. Rules like "open an issue first" and others have been there from the beginning, but we did not enforce them because of a lack of time. Now, the goal is to strictly follow the contributor guide.

Contributor Guide changes

I suggest small changes and opting out from the main guide, which means the website will have to be added to the ignore list here.

• To keep the backlog clean, automatically close issues and pull requests with no response from the creator within 14 days
• Make it clear that closing does not mean the topic is rejected forever. It's all about keeping a clean backlog; if someone comes on day 15, they can create a new issue and point to the closed one.
• We can even have a copy/paste template message that we will post in the closed issue/PR. Also, we could have a separate nice copy/paste when we close a PR that was created without initial discussion in issues.
• We need to have a new section that describes the maintainer setup in the project.

New Maintenance Setup

Current state:

* @derberg @akshatnema @magicmatatjahu @mayaleeeee @asyncapi-bot-eve

# All .md files
*.md @alequetzalli @asyncapi-bot-eve

pages/blog/*.md @thulieblack @alequetzalli
pages/community/*.md @thulieblack @alequetzalli

README.md @alequetzalli @derberg @akshatnema @magicmatatjahu @mayaleeeee @asyncapi-bot-eve

It means we have:

@alequetzalli is the maintainer of docs.
@thulieblack is the maintainer of community content.
@Mayaleeeee is the designer we ask for an opinion where design changes are part of the PR.
@derberg @akshatnema @magicmatatjahu are code reviewers and approvers.

We have only one level of maintainers - just responsible for different parts of the repo. They all do everything, from issue triage to PR review.

The plan is to introduce two levels of maintainers - to split responsibilities into 2 roles:

• to speed up work on the website
• to have an easier way of onboarding new maintainers, who first take up one role in the project and then grow into another role if they want

Just to make it clear: we are not reinventing the wheel here. You can look up the Django, React, Kubernetes, or Node.js communities to see how they deal with projects when the amount of work is getting out of hand. In short, we can summarize that the solution more or less is always: split into 2 groups - people that review and approve and people that do triage (sometimes project form triage teams)

Proposal:

Split "Maintainer" Role into TWO:

• Triager - description inspired by the Node.js community:

  Triagers assess newly-opened issues and pull requests. Triagers are given the "Triage" GitHub role and should:
  
  * Label issues and pull requests
  * Comment, close, and reopen issues and pull requests
  * Help users and novice contributors
  
  If triagers plan to become a committer, they should consult with existing committers to slowly start gaining more rights, like approving and merging simple bug fixes.
  

• Committer

  Committers approve pull requests and maintain the project. Committers are given the "Maintainer" GitHub role and are:
  - Responsible for the technical direction of the website
  - Review and approval of pull requests that can be merged as a result
  - Responsible for onboarding new committers and triagers
  

Both, committer and triager, are part of the CODEOWNER file.

We preserve the current separation of duties related to specific topics. In other words, there are still committers just for docs or committers just for design. The same applies to triagers: there can be a triager that is responsible only for code-related issues/PRs, and there can be a triager that is responsible only for docs-related issues/PRs.

New Setup proposal

• Whoever was a maintainer now becomes a committer.
• @derberg plans to step down as maintainer in a couple of weeks after we implement changes and see things work.
• We will invite @anshgoyalevil to become a new committer responsible for code. He was prepared for the role for a few months already (related to Call for CODE Maintainers).
• We will invite @sambhavgupta0705 to be the first triager. He has contributed to AsyncAPI for a year now, and on his own, without our request, started acting as triager when we were not yet even aware we need such regular support. He will be paving the path for others with this new role.

---

Thoughts?

[quetzalliwrites]

💯 agree!! Easy YES 🙌🏽

Thank you for coming up with this proposal, I genuinely think it's a genius & responsible way to grow our maintainers.

[anshgoyalevil]

In and up for it 🚀

A small experience I would like to add from the Meshery organization.
I saw these guys have created a team named "Contributors" which works in a way that includes the contributors to their organization who have a lot of merged PRs (like 20+ or so)

They invite folks to this team if they seem important to the org.

This helps them in the following ways:

• The contributors tend to add that "Member @ ORG" title on all their profiles (They aren't forced, they do this on their own, to showcase to their network). This helps them get the audience of that contributor. (This works like magic)
• That team provides a single privilege to the contributors, i.e., Assigning Issues to new contributors, and these folks can guide new contributors on how things work in the org.
• Acts like a "Give back to the community/contributor" thing.

Assigning Issues:

I saw people are creating issues and multiple contributors throw some PR to that same issue. We can reduce this by assigning those issues to the contributors who ask for the assignment by commenting on that issue. (Most orgs don't go for this "Issue Assignment" path because it sometimes blocks important issues as new contributors try to grab those issues and show no-activity. This can be reduce too, if we allow only some kind of issues to be assigned, like issues labelled with good-first-issue)
This can be ruled like:

• Issues would be unassigned on no-activity in 7 days (or maybe 14 days), or if a maintainer forgets to unassign after the stipulated period, the other interested contributors can ask for an assignment.
• The first person to ask for an assignment would get that issue to work on
• The same person cannot be assigned 3 issues (or maybe 2) simultaneously.
• Any more?

Suggestions/Thoughts?

[derberg]

@anshgoyalevil thanks for all the input!

The only document I found is https://github.com/meshery/meshery/blob/master/GOVERNANCE.md and as I understand, Contributors in Mashery is the same what we identify as Triagers? or am I wrong?

Traiger is person that enforces contributor guide, closes PRs without issues, can assign issue, label issue, closes issue if invalid - etc. And best would be if triagers write down more detailed guidelines and rules after month or two doing the work - so it is based on experience rather than on assumptions. Like with bounty, 3 editions was an agile adjustment of rules and guidelines, and now we finalize the program. Same could be with triagers: they will see if assignment works if not, if it makes sense to use it or not, and what are the "deadlines" etc. Thoughts?

[anshgoyalevil]

Contributors in Meshery is the same what we identify as Triagers? or am I wrong?

Yes, exactly.

Totally agree with you. Let's kick off all this, and test out things iteratively, while keeping what would work best for the organization and maintainers/triagers

[akshatnema]

@anshgoyalevil I'm not confident about assigning issues to contributors. According to your concept, we can't assign medium-level issues to any new contributor, right? In that manner, we are not providing an appropriate opportunity for a contributor to showcase the skills, the contributor has. We can open all issues to new contributors and will wait for some activity from the contributor's side. If the contributor fails to show any progress on the issue, we can reassign the issue to another contributor, who is willing to work on the issue.

---

@derberg Regarding the current state of the CODEOWNERS file, I'm only concerned with @magicmatatjahu, and whether he wants to continue contributing to the project or not. Can you confirm this once from him?

[anshgoyalevil]

@akshatnema We can assign medium (and even hard issues too). The idea of allowing issues with good first issues was exemplary and we need to finalize things by testing iteratively and seeing the community responses.

Some repository triagers ask for a brief explanation/approach of how the contributor would tackle the issue. This ensures that the contributor is "Actually Interested" in the issue, and thus medium to hard issues are assigned upon a satisfactory response.

[quetzalliwrites]

📣 😈 I'm excited and proud to nominate the following docs contributors to be granted triager rights:

1. @octonawish-akcodes:
   Abhishek has contributed substantially to the work-in-progress Style Guide and has been helpful in coordinating diverse contributors to align with project guidelines. His responsiveness and accessibility make him an excellent candidate for the role of triager.

2. @BhaswatiRoy:
   Bhaswati's contributions encompass our work-in-progress Style Guide and several tasks related to the 2023 Google Season of Docs. She has demonstrated commitment to the AsyncAPI documentation project and desires to remain actively involved.

3. @TRohit20:
   Rohit was involved for the duration of the 2023 Google Season of Docs, and he successfully completed all assigned tasks. He not only grasps the workflows of AsyncAPI Docs but also provides valuable assistance to other writers within our community.

4. @VaishnaviNandakumar:
   Vaishnavi exhibited exceptional performance in her writing tasks for the 2023 Mentorship Program, standing out as the most advanced and dedicated writer in the 2023 cohort. Her technical expertise, meticulous attention to detail, and audience-oriented approach make her a star.

5. @Arya-Gupta:
   Arya has made contributions to our Style Guide and addressed miscellaneous bugs. Additionally, Arya actively participated in our 2023 Mentorship Program for the writing category and expresses a strong interest in further contributions to documentation, showing a commitment to becoming more deeply involved.

6. @J0SAL:
   Joy is highly responsive and demonstrates a commendable willingness to learn from his mistakes. Moreover, he has been of significant assistance to his fellow writer, Arya, multiple times when Arya encountered difficulties while setting up his computer environment. Joy's empathetic nature and willingness to aid fellow writers are greatly appreciated!

[derberg]

@alequetzalli sounds amazing but also you folks will have a great challange of coordinating the work. Please make sure you do it in open documentation channel in slack as it will be a great learning experience for others.

[derberg]

Just checked and technically we will solve it this way:

• Triagers and Committers are added to CODEOWNERS like we did it before
• We still have branch protection that says that one CODEOWNER approval is needed to merge

I tested with @magicmatatjahu and if someone is in CODEOWNER but on Triage rights, then Approval "is gray" - so visible but do not enable merging - which is perfect

---

So I think we are ready to go:

• CODEOWERS can be set up, and invitations to repo sent - @akshatnema is the one that can do it as I just start my 2weeks holidays
• Contributor guide updates - the best is if that is done by new Triage maintainers, some first basic rules and explanation and later updates basing on the triage experience (so we have great guide for others)

[quetzalliwrites]

@alequetzalli sounds amazing but also you folks will have a great challange of coordinating the work. Please make sure you do it in open documentation channel in slack as it will be a great learning experience for others.

Definitely! we'll all use #13_docs for communicating

[akshatnema]

@akshatnema is the one that can do it as I just start my 2weeks holidays

Sure, I will do it 🚀

But, I need to have Admins permission for that. I think @derberg forgot to switch back my permissions on repo 😅 . Can anyone do that? cc: @fmvilas

[akshatnema]

But, I need to have Admins permission for that. I think @derberg forgot to switch back my permissions on repo 😅 . Can anyone do that? cc: @fmvilas

Got resolved.

---

I've a suggestion. Due to increase of maintainers inside the website repo, there is a long list inside settings to handle the maintainers. Instead, we should now maintain teams inside maintainers, to manage the access and number of maintainers inside website repo. WDYT ? @alequetzalli @derberg @anshgoyalevil @sambhavgupta0705 @thulieblack

Teams will be like:-

• Docs Triager
• Docs Committer
• Code Triager
• Code Commiter

We then only have to invite members inside the team and rest of the permissions will be automatically handled by Github.

[derberg]

@akshatnema done 😉

[quetzalliwrites]

Sounds good to me @akshatnema 🙌🏽

[derberg]

yo, did anyone start working on new contributor guide that follows what we agreed in here?

[thulieblack]

yo, did anyone start working on new contributor guide that follows what we agreed in here?

Not as yet; I can put up an issue for it in the coming week

[derberg]

Personally I think that the best would be if the new guide is drafted by people that will be triage maintainers. The main change here is about triager role, so best if people we enabled to do this role could draft the new guide.

That would be @sambhavgupta0705 @octonawish-akcodes @TRohit20 @BhaswatiRoy @VaishnaviNandakumar @Arya-Gupta @J0SAL

Thoughts?

[octonawish-akcodes]

I'll raise a draft PR soon for this, we all can collaborate over there @derberg

[derberg]

@octonawish-akcodes any progress?

[octonawish-akcodes]

Hi @derberg I am not getting enough time due to my college and current internship ://

[quetzalliwrites]

@derberg, since these onboarding guides now fall under our 2024 GSoD proposal projects, we'll move them forward that way 👍🏻

@octonawish-akcodes, it doesn’t sound like we can rely on you to commit for docs triager tasks or these docs contributions... I think it makes sense to relieve you of this docs contribution since it will now become a 2024 GSoD task, pending selection from google of course 😸

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[AnimeshKumar923]

In progress: #2959