Skip to content

Commit f905c98

Browse files
mydeaAbhiPrasad
andauthored
docs: Add triaging docs (#12605)
This adds docs about how to triage effectively. It is rather specific to this repository/team, but parts of it may also be relevant for outside contributors. See https://github.com/getsentry/sentry-javascript/blob/fn/docs-triaging/docs/triaging.md --------- Co-authored-by: Abhijeet Prasad <[email protected]>
1 parent afb83e0 commit f905c98

File tree

1 file changed

+100
-0
lines changed

1 file changed

+100
-0
lines changed

docs/triaging.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Triaging
2+
3+
The term _triage_ originally comes from medicine and describes the process of quickly examining patients who are taken
4+
to a hospital in order to decide which ones are the most seriously ill and must be treated first.
5+
6+
By _triaging issues_, we are evaluating problems that our customers are facing and providing the appropriate level of
7+
support. The goal is to provide attention to all open issues, categorise them, and alert people when there are issues of
8+
high severity. The goal is _not_ to fix all issues or answer all the questions coming from the open source community
9+
immediately.
10+
11+
## Bug fixing 101
12+
13+
Not every bug is equally critical or time sensitive. Some things reported as bugs aren’t even bugs. If you are unsure
14+
whether something needs fixing, just reach out to your colleagues and get their opinion. When you do fix a bug, it
15+
should always go hand-in-hand with adding new tests (or improving existing ones), so we can avoid any regressions in the
16+
future.
17+
18+
## Triaging workflow
19+
20+
There are a few different ways to triage issues:
21+
22+
1. You can look at the `#feed-web-sdk` channel in Slack. This channel will automatically receive a message every day in
23+
the morning with issues that require triaging.
24+
2. You can look at the triage view in the GitHub Project Board: https://github.com/orgs/getsentry/projects/31/views/29
25+
3. (Also for external contributors) You can filter by `Waiting for: Product Owner` label:
26+
https://github.com/getsentry/sentry-javascript/issues?q=is%3Aopen+is%3Aissue+label%3A%22Waiting+for%3A+Product+Owner%22
27+
28+
Generally, all new issues that are opened by external users will receive the `Waiting for: Product Owner` label
29+
initially. Whenever a contributor replies to the issue, the label will be removed automatically. If/when an external
30+
user replies again, the label will be re-added (indicating that a response from the repo owners is expected).
31+
32+
Note that issues created by contributors themselves will not get this label applied. They will also not be added to the
33+
"Web SDK Frontend" board automatically. You'll have to add the "Web SDK Frontend" project manually to issues you create
34+
yourself as a contributor.
35+
36+
If a user replies to an issue, leading to the label being re-applied, but no response is required by a contributor, you
37+
may also remove the label manually, which will also remove it from the triage list.
38+
39+
Working through the triage queue should have the highest priority of tasks. Especially issues that are reaching the top
40+
of the triage queue (which is indicated in the `#feed-web-sdk` channel through a remaining time to triage) should be
41+
prioritised. **This does not mean that you need to fix the issue immediately,** but that you should investigate and
42+
categorize the issue as soon as possible. If an issue is hard to fix, an edge case, or otherwise unclear, feel free to
43+
reply and put the issue in backlog. You may also encourage the user to contribute a PR themselves if we are unlikely to
44+
find time to resolve the issue ourselves anytime soon.
45+
46+
### (Sentry Employees) How & when should I triage issues?
47+
48+
Ideally, you can take some time every day in the morning to look over the triage queue and identify issues that you can
49+
help triage. You will not be able to triage _every_ issue effectively, and it's OK to skip some issues if you don't know
50+
what to do. That being said, it's important to split the triaging duty between the team members, so if you see a large
51+
amount of issues that you cannot help with, try to find ways to help team members with their triage load in other ways.
52+
Sometimes, this will mean taking some extra time to look into an issue. But remember, even if it takes you longer to
53+
look into an issue than another colleague, you'll also learn stuff and you'll be more effective at triaging in the
54+
future.
55+
56+
When you start looking into an issue, you may assign the issue to yourself. This indicates to other colleagues that
57+
somebody else is already looking into the issue. Generally speaking, the first person to assign themselves/answer in the
58+
issue is considered the owner of this triaging issue, and other colleagues will generally not look into this issue
59+
anymore unless prompted. Still, if you stumble upon an issue and you feel like you have something productive to add to
60+
the conversation, feel empowered to also comment on issues owned by somebody else. Make sure to follow up on issues you
61+
started to triage, and/or pull in other colleagues as needed.
62+
63+
If a team member is out of office, make sure that issues this person started to triage continue to receive attention.
64+
65+
You can and should also move issues through the project board. You can set the status to:
66+
67+
- `Backlog`: May be done at some point
68+
- `Todo`: Should be done, feel free to pick up this issue any time
69+
- `In Progress`: This is being worked on
70+
- `In Review`: PR is open
71+
- `Done`
72+
73+
This helps have an overview of what is actively being worked on at any given time.
74+
75+
### (Sentry Employees) How much time should be spent triaging?
76+
77+
Generally, triaging should be distributed between the SDK team members as equally as possible. Every developer should
78+
contribute to triaging as much as they can.
79+
80+
Overall, developers should not spend more than 2h per day triaging & reproducing issues. If you find yourself spending
81+
more time than this, bring this up with your manager to find ways to optimize this better.
82+
83+
### (Sentry Employees) What about "inoffical" triaging?
84+
85+
In addition to Github issues, you may also be pulled into triaging duty in other ways, e.g. via Discord , StackOverflow,
86+
GitHub Discussions, or Slack.
87+
88+
Generally, if non-trivial issues are raised this way, encourage the other parties to create issues on GitHub with as
89+
much detail as possible, which also makes it easier for us to track the requests/issues. You should also include the
90+
time you spend working on such issues in your general triaging time.
91+
92+
### How to approach triaging an unknown issue?
93+
94+
If you have no idea how to approach a given issue, there are a few general ways you could start:
95+
96+
1. Ask for a more thorough reproduction. Often, an issue does not contain enough information for us to figure out what
97+
is going on. Feel free to ask liberally for more information, if the provided information is not enough.
98+
2. Ask users to enable debug logs (`Sentry.intit({ debug: true })`), and paste the logs for their app. This can contain
99+
valuable information for debugging issues.
100+
3. Ask colleagues who may have some experience with a category of issues.

0 commit comments

Comments
 (0)