One of the topics that came up at the Language Summit session on the issue and PR backlog, was the sometimes unsufficient communication between core devs and contributors on the issue tracker and PRs.
People frequently receive no response to their issues and PRs, and they have no idea why that is, or what, if anything, they can do to advance their contribution. When a bot sticks a “stale” label on a PR, it’s not always obvious who is holding up what, or who is supposed to respond to this stale label.
@willingc suggested that open issues should ideally have a clear “next action” indicated on them, so that people know where things stand.
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. Once an issue is acknowledged, the OP’s job is done - any bot complaining about it being stale is speaking to the core devs. If an issue is not acknowledged for a long time, we can ping the OP after a while through a bot (or manually with a canned response) to suggest possible reasons for this, and ways the OP could push the issue forward (is it clear? is it complete? is it still relevant? does it need to be brought to someone’s attention?).
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. An early stage contributor needs to work on something that is actively maintained by a core dev, and select issues that this core dev is interested in collaborating on. Should we agree on a standard way for a core dev to indicate that they will review a PR for an issue?
What are other ways in which we can improve communication on the issue tracker and PRs?
Much as I don’t want any more tags to deal with, I suspect we need more tags to deal with
“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).
“controversial” might also be a useful tag (or “complicated” or something along those lines), to help warn new contributors away from swooping in on issues that are harder than they look. (Maybe “needs-discussion” or “needs-agreement” would fit better?)
I really like this. The OP has done us a service (or favour) by reporting the issue, so better to not keep putting it on them to decide whether it still matters or not.
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.
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.
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.
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.
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.
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.
I think you’re missing my point about the bots treating acknowledged issues differently (this is also why it needs to be a formal marking, not just a comment from a core dev).
I was referring to marking the issue, before there is any PR.
You can sort by reactions and search by number of reactions (reactions:42), but I don’t believe you can filter by issues having a reaction from members of a particular GitHub team.
If the goal is simply to mark issues in a way understandable by the bot, a reaction on the first message is a simple and non-intrusive way of doing that: the bot can access the reaction and reply accordingly.
If instead (or in addition), the goal is to find/filter issues that haven’t been acknowledged yet, then a label (or IMHO better – the lack thereof[1]) is probably a better solution. Humans can use it in searches, and the bot can write messages when the label is added/removed and then again after a prolonged silence, pinging either the OP or the core devs depending on the presence/absence of the label.
a new/untriaged/unacknowledged label could be added automatically on new issues, and removed when the issue is acknowledged. ↩︎
I have done this on other repos and found it extremely useful for everyone involved; being able to tell at a glance based on a label why an issue is still open is really powerful (hence the needs labels on PRs ).
If that includes triagers, then I think this is a good practice. On GitHub - microsoft/vscode-python: Python extension for Visual Studio Code we used to have a classify label added on all new issues, then we said “thanks” and added the appropriate needs label to signify it had been triaged and to say (we dropped the label as we start from triage-needed and getting the issue assigned is the next step).
I think “triaged” is not quite the same as “acknowledged”. For example: someone reports a bug in some stdlib module. A triager reproduces the bug and pings the relevant expert. Arguably the issue is now triaged, but the triager is not an expert on this lib and cannot say whether this is a bug or user’s misunderstanding of how the library should work on some edge case. So the bug report is not acknowledged yet.
I actually don’t think “triaged” is a boolean state, it’s an ongoing process.
I don’t know whether it’s better to add an “acknowledged” label or an “unacknowledged” label that gets added to all new issues and is later removed. I don’t know if it matters much which way (in both cases we have the question of how we acknowledge the current open issues).
We currently have an “invalid” label (I think we quickly close those issues, not sure why we need the label). How about we add a new “valid” label and then an issue can be “valid” or “invalid” or unlabelled. A core dev’s adding “valid” could be interpreted as “I think this should be done and I am likely to help review patches for this”.
I prefer the latter: add the label by default to new issues and have a triager remove it after looking at it. This has some advantages:
it’s easy to search for issues that need attention
it’s easier to remove the label than adding it
it doesn’t add an extra label to all open issues
A triager can decide to leave the label (or even add it back), if they are not confident about the status and/or validity of issue. For example, they can ping the expert and let them remove the label after assessing the validity of the issue, or add it back on an old issue that might no longer be valid.
I wrote above why I think triage is a different thing than acknowledgement, but I share your dislike of the negativity of “unacknowledged” for new issues.
My preference would be to have labels for “valid” and “invalid”, so that it is possible to have neither (the initial state). If nobody looked at the issue in enough detail to determine whether it is valid or not, then we don’t know and there is no need for a label.
Also, “valid” is much shorter than “acknowledged” so it will take less real estate on the issues view.
(The “invalid” label is less useful than “valid”, because “invalid” issues should just be closed, but we already have it so removing it is a different discussion).
To note, as a contributor I would also find it rather harsh-sounding, and is indeed now redundant now that GitHub introduced the ability to explicitly close issues as “not planned” (a much less harsh label than invalid, IMO), which are indicated by the color and symbol of the issue icon in the UI.
First we should reach an agreement on the goals and the semantics of this new label, then we can apply it accordingly. Most of the open issues are already triaged/acknowledged, so they won’t need the label. We could still add it to issues with no replies or that lack certain labels (e.g. type-*).
My goal was to make sure that all new issues get looked at by a triager and/or core dev. The untriaged label can be used to automatically mark these new issues, so that triagers can look for them. Triagers can decide to remove the label or ping the relevant experts and let them remove it.
There is some overlapping though: if the issue has been triaged and the untriaged label removed, it’s implicitly valid/accepted (otherwise it would have been closed).
I don’t think so. Most triage work doesn’t go as far as determining whether the issue is valid. For example, putting an “expert-asyncio” label just means the issue is related to asyncio. It doesn’t mean that the user didn’t misunderstand the output and reported a valid bug that needs to be fixed.
As I mentioned above, in that case the triagers should leave the label and let the experts remove it or close the issue. This was also discussed here: Triaging/reviewing/fixing issues and PRs - #15 by ezio-melotti (and in the following two messages).
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.
).