-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
Doc: added triage section to new contributor docs #28347
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
f8872a1
to
358d37f
Compare
22ffb99
to
4c8ba46
Compare
doc/devel/contribute.rst
Outdated
Triage help is a valuable contribution because it takes a lot of time and | ||
judgement to effectively curate and resolve issues; therefore we very much | ||
appreciate thoughtful feedback to issue authors. Please do not verbatim post | ||
the output of a generative AI tool (such as chat GPT) as a response to a bug | ||
report as we expect that the issue author has either already tried that or has a | ||
reason for not doing so. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a way of working aspect of triaging. It belongs under the above linked bug triaging
docs, not here. - My idea of "Contributing guide > Getting started" is that it should give a high-level idea of the kinds contribution and direct interested people to the relevant parts of the documentation. Specific information on how (not) to do things should be in those parts of the documentation e.g. bug triaging
, not on the overview page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll move it but I put it here b/c it's similar to the "no claiming" guidance that we have under "find an issue" https://matplotlib.org/devdocs/devel/contribute.html#work-on-an-issue
Which should I move that too?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My first impulse was: This belongs in https://matplotlib.org/devdocs/devel/triage.html. But considering the definition of triage actions on that site, replying with a solution is beyond triaging. Triaging only makes sure the issue is well laid out and sorted. It does not solve it (except for invalid or duplicate issues). Therefore, I don't see that people will respond with AI as part of triaging. To make life simple here, I claim it's out of scope for the PR and we can leave that section out.
In as separate PR, you could add something like "Proposing solutions" to the https://matplotlib.org/devdocs/devel/triage.html. It should be made clear that
- it's optional (a triager may add it if they already exactly know how to solve this)
- proposals / recommendations should be well considered and well laid out. If you are not sure, better leave the response to somebody else. This also includes auto-generated AI responses are not acceptable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To make life simple here, I claim it's out of scope for the PR and we can leave that section out.
😭 that section was the whole motivation for this PR, but at least spinning it out into a new PR means this one no longer has to wait on the consensus on #28335
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, separately I think "propose a solution" is required when somebody wants to close an issue claiming it's solved.
4c8ba46
to
35532f5
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I approve the content. Take or leave my comments. You may self-merge.
doc/devel/contribute.rst
Outdated
* debugging and resolving issues | ||
* linking to related issues, discussion, and external work | ||
|
||
Helping out with triage is discussed in detail in :ref:`bug_triaging`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
With my non-native English, I feel "helping out" is not that welcoming. I read it as "We have a deficiency. Can you temporarily take over a task that we currently cannot fulfill".
I suggest either
Helping out with triage is discussed in detail in :ref:`bug_triaging`. | |
Helping with triage is discussed in detail in :ref:`bug_triaging`. |
or
Helping out with triage is discussed in detail in :ref:`bug_triaging`. | |
These tasks are discussed in detail in :ref:`bug_triaging`. |
But you know the language better, so please decide whether to keep as is or change.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But you know the language better, so please decide whether to keep as is or change.
I'll change it because your helpful review told me how what I wrote is being read & that it's not conveying what I wanted it to.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also changing it to
Our triage process is discussed in detail in :ref:
bug_triaging
which I think ties in really well w/ @rcomer's suggestion of
If you have any questions about the process, please reach out on the :ref:`contributor_incubator
doc/devel/index.rst
Outdated
:class-card: sd-outline-{primary} sd-shadow-none | ||
:class-body: sd-text-{primary} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These stylings seem to make the cards less responsive to mouse-over. There's only a minimal size/layout change:
https://output.circle-artifacts.com/output/job/5b25daa3-7646-458d-9b4d-a2b5ab7702fb/artifacts/0/doc/build/html/devel/index.html
Previously, at least the small frame changed to purple, indicating a link.
https://matplotlib.org/devdocs/devel/index.html
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will change back but that seems like a pydata-sphinx-issue maybe :/
35532f5
to
961e79b
Compare
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
961e79b
to
23aa060
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry I only just noticed you pinged for another review here. Seems good to me 👍
PR summary
Discussion from #28335 had me thinking that my issues w/ the guidance being in the wrong place was that triage is its own category of contribution and therefore it should get a section in
contribute.html
This also incorporates the guidance from #28335 (particularly language/reasoning from #28335 (comment)) and therefore supercedes it.
PR checklist