Maintainer Outstanding Questions (9/14 meeting)

This doc is a starting point for conversation. It takes questions that were posted on the 9/14 meeting notes and proposes a solution for each, based on research done on Open Source best practices and years of experience with the Open edX project.

What are maintainers expected to do vis-a-vis notifications on Discourse?

• Maintainers should have accounts on Discourse and receive some subset of notifications.

  • This must include direct mentions on posts and replies to posts made. Note that this is the default notification setting on Discourse:
    
    

    Open

    

  • It is recommended that maintainers include notifications on first posts in categories of interest, done by navigating to the topic, clicking the “bell” icon next to the New Topic button, and selecting “Watching First Post”.
    
    

    Open

    

• Maintainers should check notifications weekly.

  • To avoid feeling overwhelmed, consider having notifications skip your inbox and go directly into a folder. Check these once a week on a regular cadence - consider putting 15 minutes on your calendar once or twice a week.

  • Note: when posting a new discussion topic, it is recommended you check at least daily - discussions around things like Deprecations and new Architecture will proceed better with involved discussion.

• Maintainers do not need to jump into every “help me” issue, but should answer pointed/strategic questions such as ones related to timelines, deprecations, and roadmaps.

What does monitoring GitHub issues mean in practice?

• Check new issues at least once per sprint, and consider weekly.

  • “Ack” issues that are real, even if it’s with something like “This appears to be a real issue; we will not have time to work on this in the foreseeable future” to keep the project inclusive and let watchers know where you’re at.

  • Redirect as needed: GitHub issues are only for, well, issues. Help requests should be posted in the Open edX Discussion Forums. This is a project-wide standard.

    • For what it’s worth, Tutor has this policy and enforces it. Its Issues are reserved for, well, issues.

  • Learn to say No. This is the hardest thing to do, but please do it. Excerpts from the linked doc:

    • “If you receive a contribution you don't want to accept, your first reaction might be to ignore it or pretend you didn't see it. Doing so could hurt the other person's feelings and even demotivate other potential contributors in your community.”

    • “Don't leave an unwanted contribution open because you feel guilty or want to be nice. Over time, your unanswered issues and PRs will make working on your project feel that much more stressful and intimidating.”

    • “If you don't want to accept a contribution:

      • “Thank them for their contribution

      • “Explain why it doesn't fit into the scope of the project, and offer clear suggestions for improvement, if you're able. Be kind, but firm.

      • “Link to relevant documentation, if you have it. If you notice repeated requests for things you don't want to accept, add them into your documentation to avoid repeating yourself.

      • “Close the request”

    • Note in the doc, the author suggests the above steps can be done in just 1-2 sentences, especially if you can point to docs/ADRs/OEPs that give detail on why the submission isn’t being accepted.

• Audit old issues once per sprint to see if any updates can be given. Consider a policy of closing stale issues (ones where maintainers are waiting on authors to provide more input, and the author has not responded). Rails gives 2 weeks before closing these issues; I would not recommend less than 2 weeks, and might advocate for a looser policy around common holiday times (July & December/January)

If your team is overloaded with GH monitoring and no time, consider soliciting another maintainer (or even a triage-r, perhaps on their way to becoming a maintainer) from the community.

Should GitHub notifications be person oriented, team oriented, or at the discretion of the maintainers?

Notifications should be team-oriented. This prevents a person from being a single point of failure, and from being overloaded from being the only person who the community knows to contact. It will be good if our community knows to @ -mention a team that follows a pattern throughout the entire openedx GitHub organization. Teams may consider an “on-call” rotation so there is one specific person at any time responding to notifications.

That said, individual projects may decide that person-oriented notifications are the best way to go. So ultimately this is at the discretion of the maintainers, but should be documented in the README or in Backstage if there is a different way to tag the team.

Is a week for merging or closing a PR reasonable and sustainable?

No, this isn’t reasonable. Many PRs require back and forths that take longer than a week, particularly if the author takes awhile to respond, tests continue to fail, and/or the diff is very large requiring a careful and thoughtful review.

A new PR should be triaged within a week. During triage, a decision must be made as to whether or not the project is interested the PR, and it must be closed within this period if the project does not outright want it. Remember: Learn to say no.

Elaborating on the above: Your job is to look at the PR when it comes in, and make some kind of decision about it. Say what you know as soon as you know it, even if it’s only partial (for example, “This looks like it could be interesting, but we are busy right now. We expect we’ll be able to get back to you about it in two weeks”). Sometimes something that initially looks good may turn out to be something you don’t want; it is OK to initially say “this is interesting to us” just to close the PR later - the PR may end up being wrong for the project, and you may only realize that on deeper review. Remember that partial answers and some amount of uncertainty is always OK. Remember that we are people talking to people, not corporations making promises.

Once triaged, the maintainer team must respond within a week to an author’s updates (new commits/comments/questions that require attention - such as requests for re-review).

Maintainer teams may consider a policy of closing PRs that are stale (ones where maintainers are waiting on authors to provide more input/responses, and the author has not responded) - but the period of “staleness” can not be less than the amount of time the maintainer team is taking to respond to an author’s update. That is to say: if the maintainer team is not responding to a PR’s new commits/comments until 3 weeks have passed, the maintainer team cannot consider a PR to be stale if the author has not responded for less that 3 weeks.

Cadence for merging security updates from the requirements bot?

Merging security updates should happen once per week, and should happen no less than once per sprint.

We strongly recommend that our repos stay in sync by merging weekly. This decreases the overall burden to the maintainers team by having smaller diffs/changesets.

Consider developing community members who could take on triaging and testing these PRs as a first step to becoming a Core Contributor to your repository.

What GitHub permissions should a maintainer have for a repository that they maintain?

Currently, I am not entirely sure - maintainers should either have “Maintain” or “Admin” access to their repository.

See the GitHub repository roles table; the “Maintain” level of access includes all privileges of the “Write” access, plus a few more small things such as configuring how PR merges should behave (ie, “squash and merge” as default), deleting issues, and editing the repo’s description. “Admin” contains more permissions including managing repo secrets.

I suspect that “Admin” is the permission that maintainers need - at least occasionally. My worry is that the “Admin” permission may confer responsibility that legally we cannot confer from tCRIL to individual maintainers. I’ve tested and people with Admin on one or more repos cannot initiate a repo transfer in to the openedx org. However, any Admin would have the ability to transfer their repo out of the org, as well as delete or archive it. Also concerning is Admins to repos can add outside collaborators to their repository, which directly impacts the amount tCRIL pays to GitHub (adding an outside collaborator takes a paid seat).

I vacillate between allowing full Admin access, allowing limited Admin access, or allowing no Admin access. In the case of limited Admin access, a maintainer with “Maintain” access could request Admin access for some period of time in order to perform discrete actions, and then they’d lose it. With no Admin access, any Admin tasks would need to be done by tCRIL on-call. This latter option would potentially overwhelm on-call, although I currently have no idea the volume of Admin tasks performed over repos on a daily basis.