You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@pulsar.apache.org by tison <wa...@gmail.com> on 2023/03/28 09:19:36 UTC
[RFR] Issue triaging contribution guide
Hi,
I squashed over 1000 stale issues and PRs in Dec. 2022. During the work, I
notice that the community may lack some written guides for issue triaging,
and even if a contributor is willing to help, he/she doesn't know what to
do but just leave it as is.
I wrote a draft for this case[1]. It encourages contributors to do basic
classification and encourages committers to close issues as not planned
when it's the case.
Moving forward a valid issue requires knowledge and time, but by sharing &
aligning issue triage patterns, we can reduce a few engineering loss.
Best,
tison.
[1] https://github.com/apache/pulsar-site/pull/485
Re: [RFR] Issue triaging contribution guide
Posted by tison <wa...@gmail.com>.
Added.
I'm going to merge it later since we sooner or later need to talk about how
to triage issues. Comments after merging are always welcome.
Best,
tison.
tison <wa...@gmail.com> 于2023年4月1日周六 09:35写道：
> Hi Yu,
>
> Thanks for your suggestions!
>
> For labels, I'm going to follow up on the label page[1] in the next PR. So
> let's postpone content update until then - we shall set some cross
> references.
>
> > Does it make sense to create new labels like "priority" or "severity"?
>
> No. ASF community consists of volunteers - priority and severity are just
> misleading. Vendors can have their own page to show their promises if any.
>
> > For the cases that can close issues, can we add more applicable
> scenarios to reduce triagers "guilties"? (since we cannot satisfy all
> users and need to keep the project maintainable)
>
> SGTM. I'll add some examples for reference. And yes a triager needs some
> "templates" to comment on closing stale/invalid issues.
>
> > Re-Evaluating Closed Issues
>
> I don't think it's a triage issue. Someone searches for the same thing,
> find the value and pick it up or open a new one and refer to the previous
> on, it's always viable. See these examples:
>
> * https://github.com/apache/pulsar/issues/19910
> * https://github.com/apache/pulsar/issues/7837
>
> But we may have a sentence to encourage picking up.
>
> Best,
> tison.
>
> [1] https://pulsar.apache.org/contribute/develop-labels/
>
>
> Yu <li...@apache.org> 于2023年3月29日周三 12:15写道：
>
>> Hi tison,
>>
>> Thanks for raising this up! Just my $2:
>>
>> ==========Guide Structure==========
>>
>> Suggest optimizing the guide structure with the EPPO and 5W2H methods to
>> clarify info and improve readability.
>>
>> For example,
>>
>> ## What is issue triaging?
>> ...
>>
>> ## Why is issue triaging beneficial?
>> ...
>>
>> ## How to triage issues? (a step-by-step flow)
>> ...
>>
>> ## References
>> ### Label instructions
>> ### Issue triage checklist
>> ...
>>
>> ## Related topics
>> ...
>>
>> ==========Issue Labels Instructions==========
>>
>> To instruct users how to use issue labels, does it make sense to add
>> explanations for them?
>> Currently, we only have explanations for partial labels. [1].
>>
>> The meaning of some labels is clear at 1st glance, while some are blur.
>>
>> For example,
>>
>> - `component/ML`
>> What does this mean?
>>
>> - `lifecycle/stale`, `Stale`
>> What are the differences between them?
>> Now the issues labeled with them only show they haven't been updated for
>> some time, but no more action is taken next step. Can we define it?
>>
>> - `help wanted`
>> To help newbies find proper issues in minimal time, some communities use
>> "good-first-issuse" while others use "help wanted". We can clarify this
>> explicitly.
>>
>> ==========New Issue Labels==========
>>
>> Does it make sense to create new labels like "priority" or "severity"?
>>
>> For example, p0, p1, p2; s0, s1, s2.
>>
>> The pros (help identify and solve urgent or severe issues quickly)
>> outweigh
>> the cons (increase complexity a little).
>>
>> ==========Lean Toward Closing==========
>>
>> For the cases that can close issues, can we add more applicable scenarios
>> to reduce triagers "guilties"? (since we cannot satisfy all users and need
>> to keep the project maintainable)
>>
>> ==========Re-Evaluating Closed Issues==========
>>
>> Does it make sense to add some instructions for this?
>>
>> This happens at intervals because decisions might be adjusted based on
>> additional info that surfaces later.
>>
>> ==========Visuals==========
>>
>> Suggest creating illustrations [2] to give users a holistic and bird-eye
>> view of the whole workflow. A picture is worth a thousand words.
>>
>> ==============================
>>
>> Yu
>>
>> [1] https://pulsar.apache.org/contribute/develop-labels/
>> [2]
>>
>> https://equiptowerhamlets.nhs.uk/wp-content/uploads/2020/06/Triage-process-overview.jpg
>>
>>
>> On Tue, Mar 28, 2023 at 5:20 PM tison <wa...@gmail.com> wrote:
>>
>> > Hi,
>> >
>> > I squashed over 1000 stale issues and PRs in Dec. 2022. During the
>> work, I
>> > notice that the community may lack some written guides for issue
>> triaging,
>> > and even if a contributor is willing to help, he/she doesn't know what
>> to
>> > do but just leave it as is.
>> >
>> > I wrote a draft for this case[1]. It encourages contributors to do basic
>> > classification and encourages committers to close issues as not planned
>> > when it's the case.
>> >
>> > Moving forward a valid issue requires knowledge and time, but by
>> sharing &
>> > aligning issue triage patterns, we can reduce a few engineering loss.
>> >
>> > Best,
>> > tison.
>> >
>> > [1] https://github.com/apache/pulsar-site/pull/485
>> >
>>
>
Re: [RFR] Issue triaging contribution guide
Posted by tison <wa...@gmail.com>.
Hi Yu,
Thanks for your suggestions!
For labels, I'm going to follow up on the label page[1] in the next PR. So
let's postpone content update until then - we shall set some cross
references.
> Does it make sense to create new labels like "priority" or "severity"?
No. ASF community consists of volunteers - priority and severity are just
misleading. Vendors can have their own page to show their promises if any.
> For the cases that can close issues, can we add more applicable
scenarios to reduce triagers "guilties"? (since we cannot satisfy all users
and need to keep the project maintainable)
SGTM. I'll add some examples for reference. And yes a triager needs some
"templates" to comment on closing stale/invalid issues.
> Re-Evaluating Closed Issues
I don't think it's a triage issue. Someone searches for the same thing,
find the value and pick it up or open a new one and refer to the previous
on, it's always viable. See these examples:
* https://github.com/apache/pulsar/issues/19910
* https://github.com/apache/pulsar/issues/7837
But we may have a sentence to encourage picking up.
Best,
tison.
[1] https://pulsar.apache.org/contribute/develop-labels/
Yu <li...@apache.org> 于2023年3月29日周三 12:15写道：
> Hi tison,
>
> Thanks for raising this up! Just my $2:
>
> ==========Guide Structure==========
>
> Suggest optimizing the guide structure with the EPPO and 5W2H methods to
> clarify info and improve readability.
>
> For example,
>
> ## What is issue triaging?
> ...
>
> ## Why is issue triaging beneficial?
> ...
>
> ## How to triage issues? (a step-by-step flow)
> ...
>
> ## References
> ### Label instructions
> ### Issue triage checklist
> ...
>
> ## Related topics
> ...
>
> ==========Issue Labels Instructions==========
>
> To instruct users how to use issue labels, does it make sense to add
> explanations for them?
> Currently, we only have explanations for partial labels. [1].
>
> The meaning of some labels is clear at 1st glance, while some are blur.
>
> For example,
>
> - `component/ML`
> What does this mean?
>
> - `lifecycle/stale`, `Stale`
> What are the differences between them?
> Now the issues labeled with them only show they haven't been updated for
> some time, but no more action is taken next step. Can we define it?
>
> - `help wanted`
> To help newbies find proper issues in minimal time, some communities use
> "good-first-issuse" while others use "help wanted". We can clarify this
> explicitly.
>
> ==========New Issue Labels==========
>
> Does it make sense to create new labels like "priority" or "severity"?
>
> For example, p0, p1, p2; s0, s1, s2.
>
> The pros (help identify and solve urgent or severe issues quickly) outweigh
> the cons (increase complexity a little).
>
> ==========Lean Toward Closing==========
>
> For the cases that can close issues, can we add more applicable scenarios
> to reduce triagers "guilties"? (since we cannot satisfy all users and need
> to keep the project maintainable)
>
> ==========Re-Evaluating Closed Issues==========
>
> Does it make sense to add some instructions for this?
>
> This happens at intervals because decisions might be adjusted based on
> additional info that surfaces later.
>
> ==========Visuals==========
>
> Suggest creating illustrations [2] to give users a holistic and bird-eye
> view of the whole workflow. A picture is worth a thousand words.
>
> ==============================
>
> Yu
>
> [1] https://pulsar.apache.org/contribute/develop-labels/
> [2]
>
> https://equiptowerhamlets.nhs.uk/wp-content/uploads/2020/06/Triage-process-overview.jpg
>
>
> On Tue, Mar 28, 2023 at 5:20 PM tison <wa...@gmail.com> wrote:
>
> > Hi,
> >
> > I squashed over 1000 stale issues and PRs in Dec. 2022. During the work,
> I
> > notice that the community may lack some written guides for issue
> triaging,
> > and even if a contributor is willing to help, he/she doesn't know what to
> > do but just leave it as is.
> >
> > I wrote a draft for this case[1]. It encourages contributors to do basic
> > classification and encourages committers to close issues as not planned
> > when it's the case.
> >
> > Moving forward a valid issue requires knowledge and time, but by sharing
> &
> > aligning issue triage patterns, we can reduce a few engineering loss.
> >
> > Best,
> > tison.
> >
> > [1] https://github.com/apache/pulsar-site/pull/485
> >
>
Re: [RFR] Issue triaging contribution guide
Posted by Yu <li...@apache.org>.
Hi tison,
Thanks for raising this up! Just my $2:
==========Guide Structure==========
Suggest optimizing the guide structure with the EPPO and 5W2H methods to
clarify info and improve readability.
For example,
## What is issue triaging?
...
## Why is issue triaging beneficial?
...
## How to triage issues? (a step-by-step flow)
...
## References
### Label instructions
### Issue triage checklist
...
## Related topics
...
==========Issue Labels Instructions==========
To instruct users how to use issue labels, does it make sense to add
explanations for them?
Currently, we only have explanations for partial labels. [1].
The meaning of some labels is clear at 1st glance, while some are blur.
For example,
- `component/ML`
What does this mean?
- `lifecycle/stale`, `Stale`
What are the differences between them?
Now the issues labeled with them only show they haven't been updated for
some time, but no more action is taken next step. Can we define it?
- `help wanted`
To help newbies find proper issues in minimal time, some communities use
"good-first-issuse" while others use "help wanted". We can clarify this
explicitly.
==========New Issue Labels==========
Does it make sense to create new labels like "priority" or "severity"?
For example, p0, p1, p2; s0, s1, s2.
The pros (help identify and solve urgent or severe issues quickly) outweigh
the cons (increase complexity a little).
==========Lean Toward Closing==========
For the cases that can close issues, can we add more applicable scenarios
to reduce triagers "guilties"? (since we cannot satisfy all users and need
to keep the project maintainable)
==========Re-Evaluating Closed Issues==========
Does it make sense to add some instructions for this?
This happens at intervals because decisions might be adjusted based on
additional info that surfaces later.
==========Visuals==========
Suggest creating illustrations [2] to give users a holistic and bird-eye
view of the whole workflow. A picture is worth a thousand words.
==============================
Yu
[1] https://pulsar.apache.org/contribute/develop-labels/
[2]
https://equiptowerhamlets.nhs.uk/wp-content/uploads/2020/06/Triage-process-overview.jpg
On Tue, Mar 28, 2023 at 5:20 PM tison <wa...@gmail.com> wrote:
> Hi,
>
> I squashed over 1000 stale issues and PRs in Dec. 2022. During the work, I
> notice that the community may lack some written guides for issue triaging,
> and even if a contributor is willing to help, he/she doesn't know what to
> do but just leave it as is.
>
> I wrote a draft for this case[1]. It encourages contributors to do basic
> classification and encourages committers to close issues as not planned
> when it's the case.
>
> Moving forward a valid issue requires knowledge and time, but by sharing &
> aligning issue triage patterns, we can reduce a few engineering loss.
>
> Best,
> tison.
>
> [1] https://github.com/apache/pulsar-site/pull/485
>