Skip to content

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

Merged
merged 1 commit into from
Aug 19, 2024

Conversation

story645
Copy link
Member

@story645 story645 commented Jun 5, 2024

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

@github-actions github-actions bot added the Documentation: devdocs files in doc/devel label Jun 5, 2024
@story645 story645 force-pushed the contribute-triage branch from f8872a1 to 358d37f Compare June 5, 2024 02:01
@story645 story645 marked this pull request as draft June 5, 2024 02:18
@story645 story645 force-pushed the contribute-triage branch 4 times, most recently from 22ffb99 to 4c8ba46 Compare June 5, 2024 20:29
@story645 story645 marked this pull request as ready for review August 7, 2024 22:12
@story645
Copy link
Member Author

story645 commented Aug 7, 2024

I had made this draft out of deference to #28335, but also want a decision on this before work starts on #28476

Comment on lines 181 to 186
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.
Copy link
Member

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.

Copy link
Member Author

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?

Copy link
Member

@timhoffm timhoffm Aug 8, 2024

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.

Copy link
Member Author

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

Copy link
Member Author

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.

Copy link
Member

@timhoffm timhoffm left a 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.

* debugging and resolving issues
* linking to related issues, discussion, and external work

Helping out with triage is discussed in detail in :ref:`bug_triaging`.
Copy link
Member

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

Suggested change
Helping out with triage is discussed in detail in :ref:`bug_triaging`.
Helping with triage is discussed in detail in :ref:`bug_triaging`.

or

Suggested change
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.

Copy link
Member Author

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.

Copy link
Member Author

@story645 story645 Aug 8, 2024

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

Comment on lines 118 to 119
:class-card: sd-outline-{primary} sd-shadow-none
:class-body: sd-text-{primary}
Copy link
Member

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

Copy link
Member Author

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 :/

@story645 story645 force-pushed the contribute-triage branch from 35532f5 to 961e79b Compare August 8, 2024 22:41
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
@story645
Copy link
Member Author

Made all the changes but tweaked enough that this should maybe get a 2nd look, @rcomer or @timhoffm

Copy link
Member

@rcomer rcomer left a 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 👍

@rcomer rcomer added this to the v3.10.0 milestone Aug 19, 2024
@rcomer rcomer merged commit 1c892c2 into matplotlib:main Aug 19, 2024
22 checks passed
@story645 story645 deleted the contribute-triage branch November 21, 2024 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation: devdocs files in doc/devel
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants