DOC on issue triaging process by GaelVaroquaux · Pull Request #17907 · scikit-learn/scikit-learn

GaelVaroquaux · 2020-07-11T20:36:59Z

Working on documentation and contribution guidelines in many little places to try to have a better process with the issues.

This is still WIP, as the triaging rules are not finished. But I welcome early feedback.

Cc @cmarmo

NicolasHug

Thanks @GaelVaroquaux , made a quick pass.

There's a doc building warning which can be seen here https://112305-843222-gh.circle-artifacts.com/0/doc/_changed.html

Looks pretty solid already, should we un-draft it and mark as MRG?

NicolasHug · 2020-07-12T11:45:27Z

doc/governance.rst

+
+The triage team is composed of community members who have permission on
+github to edit, label and close issues. :ref:`Their work <bug_triaging>` is
+crucial to improve the communication in the project and limit the crowing


I think it should be "and to limit" or "limits"

Also crowing -> crowding?

doc/developers/bug_triaging.rst

NicolasHug · 2020-07-12T12:04:01Z

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,11 @@
 blank_issues_enabled: false
+contact_links:


This is great!

for other reviewers: https://docs.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser

Co-authored-by: Nicolas Hug <contact@nicolas-hug.com>

GaelVaroquaux · 2020-07-12T13:16:35Z

Thanks for the feedback, @NicolasHug, I've improved based upon it.

I agree with this that in the current state this is already an improvement, and thus we shouldn't wait too much in merging. I've changed the status to ready for merge. However, I'd like feedback from @cmarmo before we merge. She might not be able to do it today, so let us wait a tiny bit.

thomasjpfan

Thank you for putting this together @GaelVaroquaux !

thomasjpfan · 2020-07-12T14:53:10Z

.github/ISSUE_TEMPLATE/usage_question.md

 ---
 name: Usage question
-about: If you have a usage question
+about: If you have a usage question please use another channel


I have been debating if we should be using "please": https://developers.google.com/style/tone#politeness

OK, that's interesting. The subtleties of the English language are too subtle for me :).

With regards to the reference that you point to, I wonder whether we should not still use "please" here. The reference is given an example where there is no choice to make: not clicking on the button will not show the document. Here, we are asking the user to exercise some judgement.

Yea I think it is okay in this context. I have been very careful of when I use "please" these days.

thomasjpfan · 2020-07-12T14:59:08Z

doc/developers/bug_triaging.rst

+4. If a reproducible example can't be provided, add the “Bug: triage”
+   label.


If the user does not provide a reproducible example in a reasonable amount of time, how should we handle the issue? (Lets say a reasonable amount of time is one month)

Above, I suggested closing the issue. I can rework a bit to make this more apparent.

thomasjpfan

I am happy with this. We can always iterate on it as times goes on.

thomasjpfan · 2020-07-12T18:44:25Z

.github/ISSUE_TEMPLATE/usage_question.md

 ---
 name: Usage question
-about: If you have a usage question
+about: If you have a usage question please use another channel


Yea I think it is okay in this context. I have been very careful of when I use "please" these days.

thomasjpfan · 2020-07-12T18:48:07Z

doc/developers/bug_triaging.rst

+  - **close issues that cannot be replicated**, after leaving time (at
+    least a week) to add extra information


Ah I see, it's mentioned here.

cmarmo

Thanks @GaelVaroquaux.

cmarmo · 2020-07-13T09:41:43Z

doc/developers/bug_triaging.rst

+comments on the issue, while core-developpers or members of the triage
+team can edit the issue description and title.


The triage team as defined by github (see here) cannot edit descriptions and titles.

cmarmo · 2020-07-13T09:48:13Z

doc/developers/bug_triaging.rst

+4. If a reproducible example can't be provided, add the “Bug: triage”
+   label.


The "Bug: triage" is the default for issues opened with "Bug" template. The issue here is more about when the label "Bug: triage" can be replaced with the "Bug" one?

cmarmo · 2020-07-13T09:48:55Z

doc/developers/bug_triaging.rst

+   is struggling, you can try to write one yourself.
+
+   If a reproducible example is provided, but you see a simplification,
+   edit the original post with your simpler reproducible example.


or add a simpler reproducible example (triage team can't edit issue descriptions).

cmarmo · 2020-07-13T09:55:42Z

doc/developers/bug_triaging.rst

+
+- Follow up on stalled PRs, to see if they must be relabeled as
+  stalled and needing help (this is typically very important in the context
+  of sprints, where the risk is to create many unfinished PRs)


I think that a link to the documentation about stalled PRs would be appropriate here.
More generally, perhaps, a Pull Request workflow would be useful, together with the issue workflow below, but it can be addressed in another PR.

cmarmo · 2020-08-11T15:42:47Z

@GaelVaroquaux, as this PR already has two approvals, what about merging it and I will propose my modifications in a new PR? Thanks for tackling this.

GaelVaroquaux · 2020-08-11T16:25:53Z

@cmarmo is right. I'm currently swamped and having a hard time to get back to this PR.

@thomasjpfan @NicolasHug , are you OK merging this, and @cmarmo does a PR to iterate on top?

GaelVaroquaux · 2020-08-11T16:37:22Z

Thanks you @NicolasHug !!

thomasjpfan · 2020-08-11T16:42:37Z

I am happy with merging this and reviewing a PR by @cmarmo that further improves it.

Co-authored-by: Nicolas Hug <contact@nicolas-hug.com>

GaelVaroquaux added 4 commits July 11, 2020 22:32

Try to streamline the issue triaging process

d9ff54a

Better triaging instructions

bfce40d

fix invalid label

4f49ffa

Fix labels

6772f33

NicolasHug reviewed Jul 12, 2020

View reviewed changes

GaelVaroquaux and others added 3 commits July 12, 2020 15:11

Update doc/developers/bug_triaging.rst

a6cc5e0

Co-authored-by: Nicolas Hug <contact@nicolas-hug.com>

Improve based on feedback

cd6c949

Improve the text

514a258

GaelVaroquaux marked this pull request as ready for review July 12, 2020 13:14

Fix link

dcdbb86

NicolasHug approved these changes Jul 12, 2020

View reviewed changes

thomasjpfan reviewed Jul 12, 2020

View reviewed changes

thomasjpfan approved these changes Jul 12, 2020

View reviewed changes

cmarmo reviewed Jul 13, 2020

View reviewed changes

NicolasHug changed the title ~~Try to streamline the issue triaging process~~ DOC on issue triaging process Aug 11, 2020

NicolasHug merged commit 618e625 into scikit-learn:master Aug 11, 2020

cmarmo mentioned this pull request Aug 11, 2020

DOC Clarify triaging role. Remove usage question template. #18142

Merged

jayzed82 pushed a commit to jayzed82/scikit-learn that referenced this pull request Oct 22, 2020

DOC on issue triaging process (scikit-learn#17907)

c1faea4

Co-authored-by: Nicolas Hug <contact@nicolas-hug.com>

		4. If a reproducible example can't be provided, add the “Bug: triage”
		label.

		- close issues that cannot be replicated, after leaving time (at
		least a week) to add extra information

		comments on the issue, while core-developpers or members of the triage
		team can edit the issue description and title.

Uh oh!

Conversation

GaelVaroquaux commented Jul 11, 2020

Uh oh!

NicolasHug left a comment

Choose a reason for hiding this comment

Uh oh!

NicolasHug Jul 12, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GaelVaroquaux commented Jul 12, 2020

Uh oh!

thomasjpfan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thomasjpfan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmarmo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmarmo Jul 13, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmarmo commented Aug 11, 2020

Uh oh!

GaelVaroquaux commented Aug 11, 2020

Uh oh!

GaelVaroquaux commented Aug 11, 2020

Uh oh!

thomasjpfan commented Aug 11, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

NicolasHug Jul 12, 2020 •

edited

Loading

cmarmo Jul 13, 2020 •

edited

Loading