doc: clarify triager role #55775
doc: clarify triager role #55775
Conversation
highlight additional points around triager role while the GH definition of triager role allows certain actions, our project do not want to exercise those and want to be conservative
|
Review requested:
|
| @@ -60,5 +60,12 @@ activities, such as applying labels and closing/reopening/assigning issues. | |||
| For more information on the roles and permissions, see ["Permission levels for | |||
| repositories owned by an organization"](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization). | |||
|
|
|||
| triagers are requested to abstain from below actions: | |||
| * approve or request changes to a pull request | |||
There was a problem hiding this comment.
I don't think it is appropriate to ask triagers abstain from request changes to a pull request. Any contributors are welcomed to give reviews on a pull request. It's just that only collaborators can effectively block a pull request from landing (but a clear reason is still required anyway).
My feeling is that given the additional permissions as a triager, a triager should be sticking to the project standard, like the guide for collaborators:
- Welcoming first-time contributors/issue posters
- Where this is unclear, leave the issue or pull request open for several days to allow for discussion.
- Most importantly, be friendly.
There was a problem hiding this comment.
GH docs shows two different actions separately:
- submit reviews on PRs
- approve or request change to PRs
while anyone is free to review PRs, approval and request change is better reserved to committers, lest it can confuse contributors (especially new comers)?
There was a problem hiding this comment.
I can see how that'd be true for folks who have write permission on the repo but are not collaborators. I'm not sure I understand how that'd apply to triaggers. For triaggers who are collaborators: why would we be asking them to refrain? For triaggers who not collaborators: why would it different from other non-collaborator contributors?
There was a problem hiding this comment.
I think the clarification should focus on the new priviledges granted with the role and responsibility of the role. Like in the collaborator guide, the new priviledges are "writing to the repo". And in terms of the triager role, it is "managing the issues".
"Request a change" is not a new priviledge granted as a triger. Anyone, non-collaborators, can request change with the GitHub UI. And GitHub UI distinguishes effectiveness of a change request with red icons or grey icons.
There was a problem hiding this comment.
that is where the problem I guess. you both raise valid points. however when looking from the author point of view, they could get confused when a request change coming from a triager and perceive it as different (and more enforcing) than that from a normal contributor, while in reality its the same. how do we tell a triager to not pretend they have additional privilege while reviewing a PR?
There was a problem hiding this comment.
@gireeshpunathil no matter what I think, the text in the PR should clarify to whom it applies to. i.e. you're the one who should clarify, not me :D
There was a problem hiding this comment.
for me, this applies to triagers, who are wanting to exercise their triage role.
when they are also a collaborator or a tsc member, their respective role definitions augment into this one, and the highest role among all apply for a specific action. that is neither captured here, nor overridden here.
from your explanation, the action pertinent to the role was also not clear to me. review looks like an overloaded term. it comprises at least of:
- submit reviews on PRs
- approve or request changes on PRs
reference from GH docs (second column is for triagers)
I am not proposing triagers refrain from submitting reviews. instead, approving or requesting changes. triagers do not have permission to do those, but if they perform these, it may confuse authors. so make it explicit here.
There was a problem hiding this comment.
triagers do not have permission to do those
I'm not sure I agree, anyone can submit a review, approve or request changes. Anyway, I think we do not agree on whether the difference in GH UI is enough to avoid confusion, and we'll have to agree to disagree.
There was a problem hiding this comment.
and we'll have to agree to disagree.
agree.
anyone can submit a review, approve or request changes.
is it an opinion, endorsed process, or a best practice? in any case pls show me a documented evidence of this being the case - as this to me is a deviation from github defined roles and permissions.
if anyone can request changes, what is your recommendation to authors of PRs when a non-collaborator does so? are they bound to address it?
There was a problem hiding this comment.
By "anyone can submit a review, approve or request changes.", I was meaning "it is a feature that GitHub offers", I didn't mean that anyone can block a PR from landing.
are they bound to address it?
IMO yes, ideally all comments should be addressed (which doesn't not mean they have to take the suggestion, e.g. adding a comment saying "Thanks for the suggestion, I prefer not to take it" would be a way to address it)
| @@ -60,5 +60,12 @@ activities, such as applying labels and closing/reopening/assigning issues. | |||
| For more information on the roles and permissions, see ["Permission levels for | |||
| repositories owned by an organization"](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization). | |||
|
|
|||
| triagers are requested to abstain from below actions: | |||
There was a problem hiding this comment.
| triagers are requested to abstain from below actions: | |
| Triagers should refrain from the following actions: |
doc/contributing/issues.md
Outdated
| * approve or request changes to a pull request | ||
| * edit wikis | ||
|
|
||
| triagers are requested to apply caution while performing below actions: |
There was a problem hiding this comment.
| triagers are requested to apply caution while performing below actions: | |
| Triagers should apply caution when performing the following actions: |
doc/contributing/issues.md
Outdated
| * edit wikis | ||
|
|
||
| triagers are requested to apply caution while performing below actions: | ||
| * close or assign issues or prs |
There was a problem hiding this comment.
| * close or assign issues or prs | |
| * Closing and/or assigning issues or PRs. |
RedYetiDev
added
the
meta
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
| * Show no patience towards spam or troll, close the issue without interacting with it and | ||
| report the user to the moderation repository. | ||
| * If you're not able to reproduce an issue, leave a comment asking for more info and | ||
| add the `needs more info` label. |
There was a problem hiding this comment.
It can probably replace repro exists as an inverse.
| When triagging issues and PR: | ||
|
|
||
| * Show patience and empathy, especially to first-time contributors. | ||
| * Show no patience towards spam or troll, close the issue without interacting with it and |
There was a problem hiding this comment.
| * Show no patience towards spam or troll, close the issue without interacting with it and | |
| * Show no patience towards spam or trolls, close the issue/PR without interacting with it and |
| @@ -60,5 +60,21 @@ activities, such as applying labels and closing/reopening/assigning issues. | |||
| For more information on the roles and permissions, see ["Permission levels for | |||
| repositories owned by an organization"](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization). | |||
|
|
|||
| triagers are requested to abstain from below actions: | |||
| * approve or request changes to a pull request | |||
There was a problem hiding this comment.
| * approve or request changes to a pull request | |
| * Approving or requesting changes to a pull request. |
highlight additional points around triager role