Onboarding documentation

For new maintainers:

• triaging rights give you access to labelling issues, add new labels, close issues or PRs, assign issues/PRs (on top of being able to comment on prs and issues that everyone has)

• this will give you the occasion to try and review PRs, learn the ropes while doing that and label PRs that you think are ready to go as consider for merge so that maintainers with merge rights can do their job faster

• if you see a PR that is currently stuck because the person that opened it needs to do something to make the PR into a mergeable state you can use the "needs reporter action" label. This label will automatically be removed by a Github Action when there is an activity on the PR (see .github/workflows/unlabel.yml)

• aside from a very small number of exceptions (that would probably arise in the meetings), every PRs can be reviewed, PRs are assigned to everybody at the same time by default as long as there isn’t a consider for merge label on it. This is because maintainers usually have only a short time to do the review on their free time and the sheer number of github notifications does not help remember which PRs have been updated and need to be re-reviewed. Plus, it is generally better to have several eyes on each PRs to catch things that another hasn’t seen.

• it is best if you can attend the weekly maintainers’ meeting, but no pressure if you can’t make it for whatever reason. If you want to come and the time and day of the week doesn’t suit you please tell the others on the group chat so a new time/day that works for everyone can be chosen.

  • the meeting is here so that maintainers coordonate on actions to take, it helps with motivations and helps to force ourselves collectively to look at harder problems or longer-running PRs/issues that maintainers individually wouldn’t have the time, knowledge or motivation to do alone.

  • for new-comers it also helps learn by watching how maintainers treat PRs and issues, as well as a time to try and review some and ask questions directly (answers are faster on voice calls and more interactive than on the group chats)

  • outside of discussions, meetings usually consist of every maintainers looking at one PR on their own, saying which one they chose to work on and review. This way if there is any questions or things that you notice, or even unremarkable things just to say to be more social, say it if you want, it makes the atmosphere more enjoyable for everyone ^^

  • if you won’t be able to do the maintenance in the next weeks or so you can say it at the meeting or in the group chat depending on what’s easier

  • for maintainers: always start the meeting asking how’s everyone doing and if they have any issues

  • if possible, it’s nice to have the major changes (CI, new maintainers, …) added to https://github.com/ocaml/opam-repository/wiki/Meeting-notes

    • at the start of every meeting, it would be nice if someone remembers to take some notes (only the major stuff, no pressure) so that some sort of coordination can be seen from the outside.
    • questions from new maintainers should probably go in the meeting notes

  • the typical agenda for the meetings is at https://github.com/ocaml/opam-repository/wiki/Meetings-agenda, please modify it if it is out of date and try to remember to use it (the wiki is a bit out of the way ^^"")

• when reviewing a PR, if you’re not sure of something it’s usually best to ask on the group chat instead of on the PR instead if it’s a question for maintainers (easier for other new maintainers to also get that information and talk, also github notifications suck there are just too many of them)

• Anyone can make "suggestions" to any PRs by going to the "Files changed" tab in the PR, clicking on the + at the line you want to do the suggestion at, and clicking on "Add a suggestion" button right after the preview tab. Then click on "add a single comment", or if you want to make several suggestions, click on "start a review", add more suggestions then click on "review changes" at the top right of the page and click "submit review" to make all the suggestions you just made appear at once.

For current maintainers:

• do frequent calls for maintainers, e.g. every months if needed or every 6 months if there are already enough people (people will leave over time so it's best to do calls and training in advance)
• when someone is interested, have a meeting with them to show this here document and to assess trust
• if trust can be given, give them triaging rights on github (opam-repo --> settings --> collaborator --> add people)
• after a couple months, when the person shows enough knowledge to be trusted with merge right, upgrade their rights to "write".
  • add them to the MAINTAINERS json list in "settings --> secrets and variables --> actions --> variables" (for the github action)
• upgrade to "admin" right when they show uncompromised trust and knowledge
• upgrades to write and admin rights should be decided between all the active maintainers