Improve communication with contributors on the issue tracker and PRs (Language summit follow up)

[ezio-melotti]

I agree that improving communication is generally a good idea.

There are a few things we could tell to the contributor:

• that we saw their issue/PR
  • this happens implicitly if someone triages the issue and/or comments
• that the issue/PR is “valid”
  • this could happen implicitly (the issue has been triaged and not rejected)
  • or explicitly (a core dev commented approving the request)
• that they need to do something
  • devs can request for more information/clarifications (possibly setting it as pending)
  • on PRs bots already ask for issue numbers, news entries, signing the CLA, etc.
  • on PRs reviewers and commenters can request for specific changes
• that they already did everything they could
  • this can be done with a comment

If the contributor can’t do anything else, we can still tell them, but this only acknowledges that the contributor is now impotent, and the fate of the issue/PR is in our hands – it doesn’t solve the frustration of seeing their issue/PR sitting there.

---

@iritkatriel

@willingc suggested that open issues should ideally have a clear “next action” indicated on them, so that people know where things stand.

@steve.dower

“needs-expert”, “needs-patch”, “needs-review” (or maybe “needs-merge”) might be a good starting point for tracking issues through our process (in a way that indicates an action, rather than a state).

This is what the stage field of BPO was used for, but we decided to drop it – see Map bpo issue metadata to GitHub fields/labels · Issue #5 · psf/gh-migration · GitHub :

To summarize:

• The resolution s can be dropped (can be mentioned in the closing message)
• The stage s can be dropped, since they can be inferred by other elements in the UI (linked PRs, requested reviews, backport labels, closed/merged issue/PR)
• …

This doesn’t cover all cases though (see this flowcharts for other possible stages), so there could be some room for improvements.

There was also some discussion about stages starting in GitHub Issues Migration: label mapping - #12 by iritkatriel (and a number of other discussions/issues about close/pending that are a bit tangential for this topic).

---

@iritkatriel

The first action on an issue is for it to be understood and acknowledged as valid by one of the core devs. It may help to add a way to mark issues as such.

Marking the issue as acknowledged is somewhat moot if no further action is then taken to resolve it.

The acknowledged label was also discussed here: Triaging/reviewing/fixing issues and PRs - #15 by ezio-melotti

acknowledged / accepted might also create expectations in the author, and has the disadvantage that most open issues will end up with an extra label. Searching for -label:acknowledge might also bring up old/triaged issues that are awaiting for more information, an expert opinion, or are still being discussed, making it more difficult to find untriaged issues.

---

@iritkatriel

Another communication gap we currently have is with new contributors, who would like to know which issues they can work on, for which a PR is likely to be reviewed.

This is an interesting observation. I wonder if it would be useful to generate a list of “active modules” based on the number of commits they received recently. This might be more effective than simply looking at modules that have a maintainer, and might find modules that don’t have a specific maintainer listed but still receive commits/reviews.

---

@iritkatriel

Should we agree on a standard way for a core dev to indicate that they will review a PR for an issue?

Usually I either just review it directly or assign it to me and come back to it later. A bot could tell the contributor that "Now <core-dev> is assigned to this issue/PR and is in charge of it.", but again it won’t make much difference if then the core dev takes a long time to reply.

---

@iritkatriel

What are other ways in which we can improve communication on the issue tracker and PRs?

On top of the ones you already mentioned, another option is to use reactions on the first message of the issue/PR such as and on the first message of the issue/PR. This could be used as as simple and less-spammy way of informing the OP that the issue/PR has been seen/acknowledged/accepted.

Another option is leveraging issue/PR templates to set expectations. They could say e.g. that

• a from a core dev means that the issue/proposal is acknowledged/accepted
• if there is anything they can do, they will be asked to do it
• some parts of the code base are currently without a maintainer
• sometimes it takes a long time for core devs to review/merge PRs

The templates could also link to the devguide and more information and suggestions (e.g. look at the git blame to find potential reviewers) can be listed there.