Automate `paper work` around project governance

[derberg]

this issue is a refreshed version of https://github.com/asyncapi/.github/issues/47

Main goal

Make sure that all the work we do around AsyncAPI governance is automated.

Technical skills needed to complete it

• You need to be ready that after completing this task you will become GitHub Actions expert
• JavaScript will be needed for scripting and calling APIs
• You will learn using GitHub API in action, hard to specify if it will be GraphQL or REST
• You will write some documentation and use mermaid.js for flow diagrams

Primary goal

• TSC members list becomes Maintainers list
• We do YAML instead of JSON. But we push JSON to website repo as before. Minor change in website code will be needed, in case of building TSC members UI
• New Maintainers.yaml can get new records only by bot:
  • we need a workflow that validates if new record is added/removed by bot and block PR in case it is a human, with a proper message
  • we need a workflow in all repositories that listens to changes in CODEOWNERS file. If maintainer is added or removed then Maintainers.yaml gets an update:
  • we can pick GitHub user name, and twitter from the API, and name of maintained repo
  • in PR where we update Maintainers.yaml bot should ping affected people
  • if maintainer was already in Maintainers.yaml but as maintainer of other repos, we just update the list of repos the maintainer takes care of
• We allow humans only to update things like:
  • linkedin and other social info
  • property like tsc_member that specifies if maintainer wants to be TSC member
• When we have new maintainer:
  • bot needs to call GitHub API to invite maintainer to AsyncAPI organization
  • we need new team in GitHub that lists all maintainers and bot should add new maintainer to it
  • if tsc_member value change, then we need to call API to either add or remove member from tsc team
• When there is a PR that modifies tsc_member to true:
  • After merge:
  • bot should post a message to new member about ways on how to get notified whenever tsc members are called out (just a text as we already have notification login in place)
  • bot should notify other TSC members (mention GH team) that new member is added
• Once someone is removed from Maintainers.yaml file because they no longer maintain any repository:
  • there should be a separate update done in the new Emeritus.yaml file that lists all people that left the project.
  • we need to remove people from organization and also proper teams
  • merge of such PR should not be automatically merged by a bot but reviewed by a human
• We need all of it to be documented, kinda flow diagram probably as well.
• We need to update official Charter that was agreed with Linux Foundation, that there is no longer a concept of Voters file. We just need to remove technical details that we should not have there in first place and simply put info that how we handle TSC/Maintainers list is described in separate Governance file, that is it.
• MAINTAINERS.yaml would also contain aggregated information about a number of TSC members, per company info, and how many more can be added by given company at a given moment

Stretch goal - depending how much time left

This is something extra for that assignment. It will be super easy as a person working on the above topics will already be an expert in GH Actions, GitHub API, and other things.

We do not really need a voting app. Voting we have already well established with GitHub. By "voting app" I mean we need a workflow that will run periodically and check every single discussion where TSC was mentioned, and out of it maintain a list of all the topics, and list of TSC members that were active in discussion (like left emoji or comment). So we keep track of all topics and TSC activities in one place.

[octonawish-akcodes]

I am interested :)

[Krishks369]

Contributing this feature will be of great use for the community and would love to have this learning experience

[dante381]

@derberg Could you recommend a few resources that we can refer to for github Actions? And a few issues to understand the workflow. Thank you

[aku1310]

Hi there,

I'm excited to express my interest in contributing to this project. As I was going through the project ideas for GSoC under Postman, this one caught my attention. I believe that my skills in JavaScript and GitHub Actions make me capable of contributing to the success of this project. Additionally, I am eager to learn more about using GitHub APIs and mermaid.js to create flow diagrams.

I understand the expected difficulty level and time commitment of the project and assure you that I am fully committed to working on it. While I am new to working with YAML, I am confident that I can quickly learn it and make contributions to the project. I am also interested in tackling smaller issues that can help me get more familiar with the codebase and show my abilities. Are there any first-time contributor issues available that I could work on to get started?

I look forward to hearing more about how I can contribute to this project.

[sambhavgupta0705]

Hi , I am Sambhav Gupta,a full stack web developer from India. I am interested in working on this issue during GSOC'23.

[14Richa]

Thanks for a detailed explanation @derberg, this looks like an interesting task that I can contribute to.

I have a couple of questions:

1. Some of the tasks are unrelated with each other example:
   • Allowing humans to update social links
   • Adding a new maintainer to AsynAPI org

Do we plan to have different workflows for these? I think we would need separate workflows to handle all of these tasks.

2. Do you think it makes sense to open sub-issues for an independent workflow so that we can merge PRs in chunks?

Also, how to start the contribution do we need to fork and then contribute?

[derberg]

Regarding good first issues related to GitHub Actions:

• https://github.com/asyncapi/.github/issues/41 touches GH Actions and also GH GraphQL API

I don't think we have others related to GH Actions atm. It is a good exercise to go through and see our existing workflows, how they're built, and what technics we use in them, as it will help to work on this task long term. Also create your own projects and add some GitHub Actions to them to see how it works. Or just add GH Action to one of the projects that you already have. If you do not have an idea what that could be, send me a link and I give ya some.

Some of the tasks are unrelated with each other example

I do not know what the ultimate solution is, but I'm almost 100% sure this will not be only one workflow. Adding a new maintainer to AsynAPI org most probably will be a core, and most "complicated" one with a need for some custom JS code and call GH GraphQL or REST API. Allowing humans to update social links will probably be a much simpler workflow where you react to changes in the specific file (TSC members), have some JS that check what changes were done, and in case changes are not related to social media links, then there will be a need to drop an error and block merge.

Do you think it makes sense to open sub-issues for an independent workflow so that we can merge PRs in chunks

This is definitely a way to go forward once we start working on that. We just didn't do it yet, as we do not know yet who will work on this issue

how to start the contribution do we need to fork and then contribute

yes, always forks, even maintainers work through forks. Imho every other approach is an anti-pattern. We have some best practice for it https://github.com/asyncapi/community/blob/master/git-workflow.md

---

Hope that helps folks. Feel free to ask for more clarification.

[aku1310]

Thank you for the guidance and clarification about this issue.

Could you also shed some light to the specific steps that need to be taken in order to be considered a potential contributor for the GSoC project? Would contributing to this or other relevant projects within AsyncAPI be a requirement, if the selection process would be based solely on the submitted proposal, or if other factors would come into play.

Thank you for taking the time to clarify these details.

[derberg]

no worries, happy to help.

when I evaluate proposals, I always value the most these that come from people that already started contributing, because I know that these are people that already started working with AsyncAPI community and knows basics on how contribution process looks like.

I do not care much to what project people contribute, we have over 60 here in AsyncAPI and they all work the same, contribution flow is the same in 99% of them.

So yeah:

• join our Slack if you are not there yet https://asyncapi.com/slack-invite and introduce to the community
• grab some good first issue from community dashboard https://www.asyncapi.com/community/dashboard

I hope that helps

[sambhavgupta0705]

Hey @aku1310 ,you may also follow this link for good first issues:)

[sparsh-989]

Hey ,I am Sparsh Agrawal final year undergrad at NITK Surathkal I'm well versed with writing scripts in Node js for such automation I have gone through all the requirements and currently working on updation of maintainer.yml by bot as soon as we make changes in the CODEOWNERS file of a particular repo and have successfully done it for my local repos.

Few questions regarding some requirements:

1. Bot should notify other TSC members (mention GH team) that new member is added Whether this notification is sent through slack using github actions orr just by a mail?
2. There should be a separate update done in the new Emeritus.yaml file that lists all people that left the project. Emeritus.yaml: what does this file contain ,is it like already contained list of maintainers who left the project?
3. Regarding addition of new maintainer to Async api Since we are trying to implement a bot, Do we need to automate the invitation process which is already there under settings tab because its neccessary for a maintainer to accept invite in order to make them a part of GH team?

[derberg]

Welcome!!!

Bot should notify other TSC members (mention GH team) that new member is added Whether this notification is sent through slack using github actions orr just by a mail?

mention of the team is enough. We already have automation that picks that up and send additional notification to email and slack

Emeritus.yaml: what does this file contain ,is it like already contained list of maintainers who left the project?

yeah, I think it will be exactly the same structure than the other file

Since we are trying to implement a bot, Do we need to automate the invitation process which is already there under settings tab because its neccessary for a maintainer to accept invite in order to make them a part of GH team?

you are referring to access level permission on repo level? we leave it manual for now, that part we want to automate through different implementation, where this kind of settings are stored as YAML file per repo, so we do not call directly the API, but long term bot can just update config. Anyway, out of scope.

the only part about permissions that is in scope and involves calling API is invitation of the user to the organization and adding them to proper team

[sparsh-989]

Thanks for clarification

[sparsh-989]

Hey 1,we can pick GitHub user name, and twitter from the API, and name of maintained repo In this whenever we update CODEOWNERS file we can get maintained repo and GitHub user name but for twitter, linked in details if we are fetching it through github api then we need the github token for that particular username and it can only be generated by that user so are we storing that token previously in a separate file . For example suppose i have username xyz-989 its the first time i am getting assigned a repo my data will not be their in the maintainer.YML so when i add my data through bot since i have made a CODEOWNERS from where will the information of twitter, linked will be filled because if we fetch it through api then we need github token but as a first timer my token will be with me only so do i update these details manually Orr we have to give my token to a file from where the bot can fetch this data for me

I need clarification regarding this

[14Richa]

Hey! I am working on an adjacent issue that involves automating a lot of administration work. Here's a draft PR. Sharing it here, in case anyone wants to give feedback or take inspiration from.

[derberg]

In this whenever we update CODEOWNERS file we can get maintained repo and GitHub user name but for twitter, linked in details if we are fetching it through github api then we need the github token for that particular username and it can only be generated by that user so are we storing that token previously in a separate file . For example suppose i have username xyz-989 its the first time i am getting assigned a repo my data will not be their in the maintainer.YML so when i add my data through bot since i have made a CODEOWNERS from where will the information of twitter, linked will be filled because if we fetch it through api then we need github token but as a first timer my token will be with me only so do i update these details manually Orr we have to give my token to a file from where the bot can fetch this data for me

Profile information is public unless you explicitly hide it (I think you can hide email). There is explicit twitter info one can provide. Other info, is not there, yes, and this is something maintainer can manually update in the maintainers.yaml. This is the only human-change that will be allowed, not add/remove but update in the list. As it comes to toke, I think that if someone provided twitter info, anyone can read it with any token.

[pragya-20]

Hi there! My name is Pragya Bhardwaj, and I am a Software Developer based in India. I specialize in working with Javascript, JSON, Node.js and have experience developing mobile applications using these technologies.

While reviewing the project description, I am particularly excited to work with Github's actions and workflows. I have already built a few flows, recently started exploring mermaid.js, and have found them to be a powerful way to automate tasks. I am eager to work with the team and contribute to this project.

I was reading the thread and wanted to understand a few things:

1. For Emeritus.yaml: shouldn’t we update the tsc_member property in the file to be false if the maintainer has been removed from the GH and other teams?
2. Also, in maintainers.yaml file, we were letting the maintainer do that update but for Emeritus.yaml, the bot should handle this part.

Thanks!

[derberg]

Hey @pragya-20 👋🏼

For Emeritus.yaml: shouldn’t we update the tsc_member property in the file to be false if the maintainer has been removed from the GH and other teams?

do you mean that instead of maintaining Emeritus.yaml we should just change tsc_member in new maintainers.yaml? what if someone is not maintainer anymore?

Also, in maintainers.yaml file, we were letting the maintainer do that update but for Emeritus.yaml, the bot should handle this part.

sorry but I did not get this one

[sparsh-989]

Hey @derberg I have implemented some of the above required features and here is the link to the document which contains its working video and the used workflow and scripts. https://docs.google.com/document/d/1mjCX8uc0ZjA1rae9rbeYMWRHhNOPG6_eGsOiVbZswuw/edit?usp=sharing I have given access to this mail id - lpgornicki@gmail.com , let me know if any other mail id's need to be given access , waiting for valuable suggestions from your side. Thanks!

[pragya-20]

Hi @derberg I have contributed to this issue via this PR. Excited to work on this project :)

Thanks!

[pragya-20]

Hi @derberg , Thanks for your response.

do you mean that instead of maintaining Emeritus.yaml we should just change tsc_member in new maintainers.yaml? what if someone is not a maintainer anymore?

Nope, I didn't mean that. I meant when a maintainer is removed from the MAINTAINERS.yml file and added to the Emeritus.yml file, certain properties like tsc_member should be updated to false before appending the record to the Emeritus.yml file as they are no longer a part of tsc.

Also, in maintainers.yaml file, we were letting the maintainer do that update but for Emeritus.yaml, the bot should handle this part.

For the second one, I wanted to understand when the bot appends the removed maintainer's record to the Emeritus.yml file, should the bot update the 'tsc_member' property by itself or does the maintainer needs to do that update?

I hope it makes sense!

[derberg]

Nope, I didn't mean that. I meant when a maintainer is removed from the MAINTAINERS.yml file and added to the Emeritus.yml file, certain properties like tsc_member should be updated to false before appending the record to the Emeritus.yml file as they are no longer a part of tsc.

this change should be done in one run, I mean removal of human from maintainers file and addition to emeritus. Then no need to do initial false switch. Makes sense?

For the second one, I wanted to understand when the bot appends the removed maintainer's record to the Emeritus.yml file, should the bot update the 'tsc_member' property by itself or does the maintainer needs to do that update?

there are 2 scenarios when someone is no longer TSC memer:

• they just "manually" resign but are still staying there as maintainers. So yeah they manually need to open a true/false related PR
• then resign as maintainers in all repos where they were maintainers, bot updates that info in maintainers.yml, and in case TSC member resigned from all repos, then the change in maintainers file is "remove from file" and then emeritus addition should take place

makes sense?

[pragya-20]

Yepp @derberg, It's clear to me now

Thank you 😃

[sparsh-989]

Hey @derberg here is my proposal Waiting for your valuable suggestions, thankyou

[derberg]

fyi folks @14Richa is the mentee for that project.

good luck @14Richa

[github-actions[bot]]

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

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 :heart:

[tejaskhanpate]

I am learn your block

[derberg]

@tejaskhanpate sorry?

[CodPro-Sui]

I want to solve bug

[derberg]

but this is not a bug

[CodPro-Sui]

I'm college student beginner sir, I'm sorry sir 👏. I was just checking how to work open source.

[derberg]

@Nau56 I definitely recommend you to have a look at https://github.com/orgs/asyncapi/discussions/892 and https://www.youtube.com/watch?v=KTnFoXY_evs