Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automate paper work around project governance #210

Open
derberg opened this issue Mar 6, 2023 · 32 comments
Open

Automate paper work around project governance #210

derberg opened this issue Mar 6, 2023 · 32 comments
Labels
enhancement New feature or request gsoc This label shoudl be used for issues or discussions related to ideas for Google Summer of Code

Comments

@derberg
Copy link
Member

derberg commented Mar 6, 2023

this issue is a refreshed version of #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.

@derberg derberg added enhancement New feature or request gsoc This label shoudl be used for issues or discussions related to ideas for Google Summer of Code labels Mar 6, 2023
@octonawish-akcodes
Copy link

I am interested :)

@Krishks369
Copy link
Contributor

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

@dante381
Copy link
Contributor

dante381 commented Mar 8, 2023

@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
Copy link

aku1310 commented Mar 8, 2023

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
Copy link
Member

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

@14Richa
Copy link
Contributor

14Richa commented Mar 10, 2023

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.

  1. 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
Copy link
Member Author

derberg commented Mar 14, 2023

Regarding good first issues related to GitHub Actions:

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
Copy link

aku1310 commented Mar 14, 2023

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.

Copy link
Member Author

derberg commented Mar 14, 2023

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:

I hope that helps

@sambhavgupta0705
Copy link
Member

sambhavgupta0705 commented Mar 14, 2023

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

@sparsh-989
Copy link

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?

Copy link
Member Author

derberg commented Mar 15, 2023

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
Copy link

Thanks for clarification

@sparsh-989
Copy link

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
Copy link
Contributor

14Richa commented Mar 17, 2023

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.

Copy link
Member Author

derberg commented Mar 21, 2023

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
Copy link

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
Copy link
Member Author

derberg commented Mar 27, 2023

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
Copy link

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 - [email protected] , let me know if any other mail id's need to be given access ,
waiting for valuable suggestions from your side.
Thanks!

@pragya-20
Copy link

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

Thanks!

@pragya-20
Copy link

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!

Copy link
Member Author

derberg commented Mar 30, 2023

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
Copy link

Yepp @derberg,
It's clear to me now

Thank you 😃

@sparsh-989
Copy link

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

@derberg
Copy link
Member Author

derberg commented May 18, 2023

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

good luck @14Richa

@github-actions
Copy link

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 ❤️

@github-actions github-actions bot added the stale label Sep 16, 2023
@tejaskhanpate
Copy link

I am learn your block

@github-actions github-actions bot removed the stale label Sep 30, 2023
Copy link
Member Author

derberg commented Oct 2, 2023

@tejaskhanpate sorry?

@CodPro-Sui
Copy link

I want to solve bug

Copy link
Member Author

derberg commented Oct 4, 2023

but this is not a bug

@CodPro-Sui
Copy link

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

Copy link
Member Author

derberg commented Oct 7, 2023

@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request gsoc This label shoudl be used for issues or discussions related to ideas for Google Summer of Code
Projects
None yet
Development

No branches or pull requests

12 participants