Skip to content

Update the triage/triaging.rst page. #914

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.

Sign up for GitHub

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 8 commits into from
Oct 8, 2022
Merged

Update the triage/triaging.rst page. #914

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1b14292
Update the triage/triaging.rst page.
ezio-melotti Jul 12, 2022
e4f4a77
Mention the `triaged` label + more tweaks.
ezio-melotti Aug 6, 2022
19db210
Fix markup.
ezio-melotti Aug 6, 2022
87c3027
Merge branch 'main' into update-triaging
ezio-melotti Oct 7, 2022
e928c57
Add a link to the `triaged` label.
ezio-melotti Oct 7, 2022
034b1a3
Apply suggestions from code review
ezio-melotti Oct 8, 2022
5bd2948
Address more review comments.
ezio-melotti Oct 8, 2022
f530bca
Apply suggestions from code review
ezio-melotti Oct 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions core-developers/committing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ to enter the public source tree. Ask yourself the following questions:
require a ``NEWS`` entry. (See the following section for more information.)


.. _news-entry:

Updating NEWS and What's New in Python
--------------------------------------

Expand Down
88 changes: 40 additions & 48 deletions triage/triaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,24 @@ Triaging an Issue
This section of the devguide documents the :ref:`issue tracker <tracker>` for
users and developers.

Contributors with the Triager role on the issue tracker can triage issues
directly without any assistance.


Checklist for Triaging
======================

* Read the issue comment(s).
* Review and set classification fields
- Title: should be concise with specifics which are helpful to someone
scanning a list of issue titles. (Optional, if possible) Add a
prefix at the start of the title to indicate the module, e.g. IDLE,
doc, or async.
- Type
- Stage
- Components: multiple items may be set
- Versions: set if known, leave blank if unsure. Multiple items may be set.
* Review and set process fields
- Status
- Superseder
- Assignees
- Nosy List
- Priority
- Keywords
* (Optional) Leave a brief comment about the proposed next action needed. If
there is a long message list, a summary can be very helpful.
* Check that the title is concise with specifics which are helpful to
someone scanning a list of issue titles.
* For pull request, ensure that the corresponding issue is added before
the title (``gh-NNNNN: ...``).
* Read the initial message and the comments.
* Set all the relevant :ref:`labels <gh-labels>`.
* Where appropriate, you might set the "Assignees", "Reviewers", and
"Projects" fields.
* You might also leave a brief comment about the proposed next action needed.
If there is a long message list, a summary can be very helpful.
* Finally, you can set the :gh-label:`triaged` label (unless you want other triagers
to take a look).
Copy link
Member

@iritkatriel iritkatriel Oct 7, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is so far the first and only documentation we have about the "triaged" label, so let me try to understand what it's for. The idea is that if a triager does not want other triagers to look at the issue, they put a triaged label?

Why would a triager not want other triagers to look at the issue?

Is it then offensive for another triager or core dev to change the labels on the issue (undermining a decision that another triager marked as 'final')?

This sounds to me like the opposite of how we work. It's the equivalent of a label that a no-committer can put on a PR to say "this has been reviewed. I do not want other non-commiters to review it". We don't have this label. We have the "awaiting core review" label which indicates that a non-committer has reviewed, but it does not dis-invite further reviews from non-committers.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see now that if I hover over the label it says "The issue has been accepted as valid by a triager". Which is quite different from what is implied by this doc.

I don't think validity is something we expect triagers to decide about (when I proposed a "valid" label I tried to be clear that it is to be used by subject matter experts, not triagers). If you think that this is for triagers to decide, then this doc should explain how a triager is supposed to make that decision. If you don't think that, then the tooltip on the "triaged" label needs to change to whatever it is that this label means.

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 don't remember the exact timeline, but I wrote that sentence on Aug 6 and I might have added the label description on GitHub later after more discussions.

However it seems there is still no clear consensus on how it should be used. Are you at the sprints? Perhaps it could be discussed there.

Regarding this specific PR, it is mostly about updating the checklist, not documenting the label itself. I can remove or change the sentence, and possibly re-add/update it again in next iteration. I also have another incoming PR (#930) where I can document it more extensively.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What meaning did the Steering Council intend when they approved the new term?

I agree with deferring the Triaged sentence to get on with the improved list.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://discuss.python.org/t/improve-communication-with-contributors-on-the-issue-tracker-and-prs-language-summit-follow-up/15812/30, in particular:

The triaged label would signify that the process is done (for now, at least) – and since the issue wasn’t closed, it’s “valid” and waiting for a core dev.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you at the sprints? Perhaps it could be discussed there.

I'm online, but I don't feel able to contribute on this matter beyond commenting on whether I think the documentation is consistent and clear.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea is that if a triager does not want other triagers to look at the issue, they put a triaged label?

No, the idea is that if a triager thinks there is nothing more a triager can do, they mark the issue so others don't need to re-read it.

Is it then offensive for another triager or core dev to change the labels on the issue (undermining a decision that another triager marked as 'final')?

That would be like any other disagreement. It could be done in an offensive way, but hopefully won't.

this has been reviewed. I do not want other non-commiters to review it

I'd word it as “This has been reviewed. Other non-commiters are free to re-review it, but I believe their time would be better spent elsewhere.”

(I don't speak for the entire Steering Council here.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The triaged label would signify that the process is done (for now, at least)

Does “for now, at least” mean that the triaged label will be removed by a bot after a certain amount of time? Or how else will it work long term?


Note: some of these fields can only be set/edited by core developers.


.. _helptriage:
Expand All @@ -41,14 +33,13 @@ Helping Triage Issues
=====================

Once you know your way around how Python's source files are
structured and you are comfortable working with patches, a great way to
structured and you are comfortable with the workflow, a great way to
contribute is to help triage issues. Do realize, though, that experience
working on Python is needed in order to effectively help triage.

Around the clock, new issues are being opened on the :ref:`issue tracker
<tracker>` and existing issues are being updated. Every issue needs to be
triaged to make sure various things are in proper order. Even without special
privileges you can help with this process.
triaged to make sure various things are in proper order.

Classifying Reports
-------------------
Expand All @@ -62,44 +53,45 @@ For bugs, an issue needs to:
These are things you can help with once you have experience developing for
Python:

* try reproducing the bug: For instance, if a bug is not clearly explained
enough for you to reproduce it then there is a good chance a core developer
* Try reproducing the bug: for instance, if a bug is not explained clearly
enough for you to reproduce it, then there is a good chance a core developer
won't be able to either.
* see if the issue happens on a different Python version: It is always helpful
* See if the issue happens on a different Python version: it is always helpful
to know if a bug not only affects the in-development version of Python, but
whether it also affects other versions in maintenance mode.
* write a unit test: If the bug lacks a unit test that should end up in
* Write a unit test: if the bug lacks a unit test that should end up in
Python's test suite, having that written can be very helpful.

This is all helpful as it allows triagers (i.e.,
:ref:`people with the Developer role on the issue tracker <triagers>`) to
properly classify an issue so it can be handled by the right core developers in
a timely fashion.
This is all helpful as it allows members of the :ref:`triage team <triage-team>`
to properly classify an issue so it can be handled by the right core developers
in a timely fashion.

Reviewing Patches
-----------------
Reviewing Pull Requests
-----------------------

If an issue has a pull request attached that has not been reviewed, you can help
by making sure the patch:
If an issue has a linked pull request that has not been reviewed,
you can help by making sure the pull request:

* follows the style guides
* applies cleanly to an up-to-date clone
* is a good solution to the problem it is trying to solve
* follows the style guides
* includes proper tests
* includes proper documentation changes
* submitter is listed in ``Misc/ACKS``, either already or the patch adds them
* includes a :ref:`NEWS entry <news-entry>` (if needed)
* includes the author in ``Misc/ACKS``, either already or the patch adds them
* doesn't have conflicts with the ``main`` branch

Doing all of this allows core developers and :ref:`triagers <triage-team>`
to more quickly look for subtle issues that only people with extensive
experience working on Python's code base will notice.

Doing all of this allows core developers and :ref:`triagers` to more
quickly look for subtle issues that only people with extensive experience
working on Python's code base will notice.
See also :ref:`committing`.

Finding an Issue You Can Help With
----------------------------------

If you want to help triage issues, you might also want to search for issues
in modules which you have a working knowledge. Search for the name of a module
in the issue tracker or use the `advanced search`_ query builder to search for
specific kinds of issues (e.g. the "Windows" label if you are a Windows
developer, "Extension Modules" if you are familiar with C, etc.).
If you want to help with triaging, you might also want to search for issues
in modules which you have a working knowledge. Search for the name of a
module in the issue tracker, filter by label, or use the `advanced search`_
to find these issues.

.. _advanced search: https://github.com/search/advanced