Document the triage process

[jkowall]

Description of the changes

Cleanup some of the existing documentation and fix some pointers to the files we have in the base repo

Created a triage policy and use of a triage tag which needs to be added to the template : jaegertracing/.github#4

How was this change tested?

Text only changes

Checklist

• I have read https://github.com/jaegertracing/jaeger/blob/master/CONTRIBUTING_GUIDELINES.md
• I have signed all commits
• [NA] I have added unit tests for the new functionality
• [NA] I have run lint and test steps successfully

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.48%. Comparing base (2eee293) to head (1fe63f8).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5466   +/-   ##
=======================================
  Coverage   95.48%   95.48%           
=======================================
  Files         331      331           
  Lines       16121    16121           
=======================================
  Hits        15393    15393           
  Misses        555      555           
  Partials      173      173           

Flag	Coverage Δ
badger_v1	8.07% <ø> (ø)
badger_v2	1.94% <ø> (ø)
cassandra-3.x-v1	16.47% <ø> (ø)
cassandra-3.x-v2	1.86% <ø> (ø)
cassandra-4.x-v1	16.47% <ø> (ø)
cassandra-4.x-v2	1.86% <ø> (ø)
elasticsearch-7.x	1.78% <ø> (?)
elasticsearch-8.x	1.78% <ø> (?)
grpc_v1	9.24% <ø> (ø)
grpc_v2	7.60% <ø> (ø)
kafka	9.80% <ø> (ø)
opensearch-1.x	1.78% <ø> (?)
opensearch-2.x	1.78% <ø> (?)
unittests	93.95% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[yurishkuro]

do you think we need to emphasize "bug" or just have a general issue management policy?

[jkowall]

The 3 issue types we have are bug, feature request, and security. I guess we can use this to encompass bug and security. I am not sure if it makes sense to have feature requests needing triage, since they are likely to be discussions or just closed out if the idea doesn't make sense. Do you think we should triage all 3 issue types?

[yurishkuro]

So bug / enhancement / etc labels are pretty orthogonal to the life cycle of the issue. I am really interested in solving the latter. I think the workflow should be very similar (ideally identical), e.g. a feature request may be poorly specified and moved into needs-info state, same as bug would. I am thinking of these states (open to change names):

• needs-triage: state for new issues or after OP provided additional info (will need automation to the latter)
• needs-info: maintainer requested more info from OP
• help-wanted: issue is accepted to be implemented, but waiting for volunteers to pick it up
• in-progress: perhaps once a volunteer is found the issue is assigned to them so that it doesn't stick in help-wanted
• wontfix: one of closed state. Technically don't need a label since closing can be done in two ways on GH: completed and not-planned.
• duplicate: closed as a duplicate of another issue (e.g. with a comment /duplicate #1234). Should it be closed as not-planned?

The not-closed states should all have their own expiration timers:

• needs-triage should be resend notification to maintainers after timeout
• needs-info should be marked stale after timeout, and closed after another timeout
• help-wanted should be marked stale after timeout, and closed after another timeout
• in-progress should be marked stale after timeout and ask the assignee if they can provide an update. After another timeout in the stale state it should transition back into help-wanted

Of course we don't have to jump to automation, I would start with just publishing the workflow & state diagram itself.

PS: I am surprised nobody created a generic GH action for supporting this kind of life cycle

[yurishkuro]

https://docs.github.com/en/actions/managing-issues-and-pull-requests/using-github-actions-for-project-management

[jkowall]

The one challenge with that and creating these rules is that once you get into stale definitions most things are going to auto close. A feature request is typically long running and may never be done. Should it be closed? Probably not, as it could happen.

The other two (bug/security) seem to have more definitive time horizons that's why I called them out. Should we build all this complexity off the bat? Probably not, I was trying to take a simple approach to this and we can add the timeouts or other workflows later.

The objective from my perspective is that it will enable me and maybe the other maintainers to help more with triage.

[yurishkuro]

if we want a simpler approach the alternative would be to forgo workflow tags altogether and just use a project board where we can drag issues between swim lanes. But without the expiration timers this will not solve the issue of every-increasing backlogs.

[jkowall]

Projects on GH are somewhat useless since they are managed outside of the rest of the issue/PR workflows.

Here is an action which seems to do what you want - https://github.com/marketplace/actions/close-stale-issues

If we were to use your tag list from above, we'd need to define which timeouts we should have. I would be fine with that list if you want to go with it.

[yurishkuro]

for reference open-telemetry/opentelemetry-specification#3821

[yurishkuro]

And the actual process doc: https://github.com/open-telemetry/opentelemetry-specification/pull/3990/files

[yurishkuro]

To clarify, I don't think we want as complex workflow as OTEL Spec, but I do like to have a state diagram that defines when & how issues are transitioned between states, with the aim that there is no state in which an issue can sit infinitely (since it just creates a never-clearing backlog)