From 5f838cf4f3dfa6b4bf96ebf260b290e50b872627 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Fri, 21 Jun 2024 14:57:23 +0200 Subject: [PATCH 1/3] docs: Add triaging docs --- docs/triaging.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/triaging.md diff --git a/docs/triaging.md b/docs/triaging.md new file mode 100644 index 000000000000..a330f496a1e5 --- /dev/null +++ b/docs/triaging.md @@ -0,0 +1,90 @@ +# Triaging + +The term _triage_ originally comes from medicine and describes the process of quickly examining patients who are taken +to a hospital in order to decide which ones are the most seriously ill and must be treated first. + +By _triaging issues_, we are evaluating problems that our customers are facing and provide the appropriate level of +support. The goal is to provide attention to all open issues, to categorise them and alert people when there are issues +of high severity. The goal is _not_ to fix all issues or answer all the questions coming from the open source community +immediately. + +## Bug fixing 101 + +Not every bug is equally critical or time sensitive. Some things reported as bugs aren’t even bugs. If you are unsure +whether a things needs fixing, just reach out to your colleagues and get their opinion. When you do fix a bug, it should +always go hand-in-hand with adding new tests (or improving existing ones), so we can avoid any regressions in the +future. + +## Triaging workflow + +There are a few different ways to triage issues: + +1. You can look at the `#feed-web-sdk` channel in Slack. This channel will automatically receive a message every day in + the morning with issues that require triaging. +2. You can look at the triage view in the Github Project Board: https://github.com/orgs/getsentry/projects/31/views/29 +3. (Also for external contributors) You can filter by `Waiting for: Product Owner` label: + https://github.com/getsentry/sentry-javascript/issues?q=is%3Aopen+is%3Aissue+label%3A%22Waiting+for%3A+Product+Owner%22 + +Generally, all new issues that are opened by external users will receive the `Waiting for: Product Owner` label +initially. Whenever a contributor replies to the issue, the label will be removed automatically. If/when an external +user replies again, the label will be re-added (indicating that a response from the repo owners is expected). + +Note that issues created by contributors themselves will not get this label applied. They will also not be added to the +"Web SDK Frontend" board automatically. You'll have to add the "Web SDK Frontend" project manually to issues you create +yourself as a contributor. + +If a user replied to an issue, leading to the label being re-applied, but no response is required by a contributor, you +may also remove the label manually, which will also remove it from the triage list. + +Working through the triage queue should have the highest priority of tasks. Especially issues that are reaching the top +of the triage queue (which is indicated in the `#feed-web-sdk` channel through a remaining time to triage) should be +prioritised. **This does not mean that you need to fix the issue immediately,** but that you should investigate and +categorize the issue as soon as possible. If an issue is hard to fix, an edge case, or otherwise unclear, feel free to +reply and put the issue in backlog. You may also encourage the user to contribute a PR themselves, if we are unlikely to +find time to resolve the issue ourselves anytime soon. + +### (Sentry Employees) How & when should I triage issues? + +Ideally, you can take some time every day in the morning to look over the triage queue and identify issues that you can +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 +what to do. That being said, it's important to split the triaging duty between the team members, so if you see a large +amount of issues that you cannot help with, try to find ways to help team members with their triage load in other ways. +Sometimes, this will mean taking some extra time to look into an issue. But remember, even if it takes you longer to +look into an issue than another colleague, you'll also learn stuff and you'll be more effective at triaging in the +future. + +When you start looking into an issue, you may assign the issue to yourself. This indicates to other colleagues that +somebody else is already looking into the issue. Generally speaking, the first person to assign themselves/answer in the +issue is considered the owner of this triaging issue, and other colleagues will generally not look into this issue +anymore unless prompted. So make sure to follow up on issues you started to triage, and/or pulling in other colleagues +as needed. + +You can and should also move issues through the project board. You can set the status to "Backlog" (may be done at some +point), "Todo" (should be done), "In Progress" (I am working on this), "In Review" (PR is open), or "Done". This helps +have an overview what is actively being worked on at any given time. + +### (Sentry Employees) How much time should be spent triaging? + +Generally, triaging should be distributed between the SDK team members as equally as possible. Every developer should +contribute to triaging as much as they can. + +Overall, developers should not spend more than 2h per day triaging & reproducing issues. If you find yourself spending +more time than this, bring this up with your manager to find ways to optimize this better. + +### (Sentry Employees) What about "inoffical" triaging? + +In addition to Github issues, you may also be pulled into triaging duty in other ways, e.g. via Discord or on Slack. + +Generally, if non-trivial issues are raised this way, encourage the other parties to create issues on Github with as +much detail as possible, which also makes it easier for us to track the requests/issues. You should also include the +time youn spend working on such issues in your general triaging time. + +### How to approach triaging an unknown issue? + +If you have no idea how to approach a given issue, there are a few general ways you could start: + +1. Ask for a more thourough reproduction. Often, an issue does not contain enough information for us to figure out what + is going on. Feel free to ask liberally for more information, if the provided information is not enough. +2. Ask users to enable debug logs (`Sentry.intit({ debug: true })`), and paste the logs for their app. This can contain + valuable information for debugging issues. +3. Ask colleagues who may have some experience with a category of issues. From 000daedc492f244b1b5b0bc1e92b82478c39205f Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Mon, 24 Jun 2024 09:48:41 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Abhijeet Prasad --- docs/triaging.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/triaging.md b/docs/triaging.md index a330f496a1e5..c2b158dfdbcf 100644 --- a/docs/triaging.md +++ b/docs/triaging.md @@ -3,15 +3,15 @@ The term _triage_ originally comes from medicine and describes the process of quickly examining patients who are taken to a hospital in order to decide which ones are the most seriously ill and must be treated first. -By _triaging issues_, we are evaluating problems that our customers are facing and provide the appropriate level of -support. The goal is to provide attention to all open issues, to categorise them and alert people when there are issues +By _triaging issues_, we are evaluating problems that our customers are facing and providing the appropriate level of +support. The goal is to provide attention to all open issues, categorise them, and alert people when there are issues of high severity. The goal is _not_ to fix all issues or answer all the questions coming from the open source community immediately. ## Bug fixing 101 Not every bug is equally critical or time sensitive. Some things reported as bugs aren’t even bugs. If you are unsure -whether a things needs fixing, just reach out to your colleagues and get their opinion. When you do fix a bug, it should +whether something needs fixing, just reach out to your colleagues and get their opinion. When you do fix a bug, it should always go hand-in-hand with adding new tests (or improving existing ones), so we can avoid any regressions in the future. @@ -21,7 +21,7 @@ There are a few different ways to triage issues: 1. You can look at the `#feed-web-sdk` channel in Slack. This channel will automatically receive a message every day in the morning with issues that require triaging. -2. You can look at the triage view in the Github Project Board: https://github.com/orgs/getsentry/projects/31/views/29 +2. You can look at the triage view in the GitHub Project Board: https://github.com/orgs/getsentry/projects/31/views/29 3. (Also for external contributors) You can filter by `Waiting for: Product Owner` label: https://github.com/getsentry/sentry-javascript/issues?q=is%3Aopen+is%3Aissue+label%3A%22Waiting+for%3A+Product+Owner%22 @@ -33,14 +33,14 @@ Note that issues created by contributors themselves will not get this label appl "Web SDK Frontend" board automatically. You'll have to add the "Web SDK Frontend" project manually to issues you create yourself as a contributor. -If a user replied to an issue, leading to the label being re-applied, but no response is required by a contributor, you +If a user replies to an issue, leading to the label being re-applied, but no response is required by a contributor, you may also remove the label manually, which will also remove it from the triage list. Working through the triage queue should have the highest priority of tasks. Especially issues that are reaching the top of the triage queue (which is indicated in the `#feed-web-sdk` channel through a remaining time to triage) should be prioritised. **This does not mean that you need to fix the issue immediately,** but that you should investigate and categorize the issue as soon as possible. If an issue is hard to fix, an edge case, or otherwise unclear, feel free to -reply and put the issue in backlog. You may also encourage the user to contribute a PR themselves, if we are unlikely to +reply and put the issue in backlog. You may also encourage the user to contribute a PR themselves if we are unlikely to find time to resolve the issue ourselves anytime soon. ### (Sentry Employees) How & when should I triage issues? @@ -56,12 +56,12 @@ future. When you start looking into an issue, you may assign the issue to yourself. This indicates to other colleagues that somebody else is already looking into the issue. Generally speaking, the first person to assign themselves/answer in the issue is considered the owner of this triaging issue, and other colleagues will generally not look into this issue -anymore unless prompted. So make sure to follow up on issues you started to triage, and/or pulling in other colleagues +anymore unless prompted. Still, if you stumble upon an issue and you feel like you have something productive to add to the conversation, feel empowered to also comment on issues owned by somebody else. Make sure to follow up on issues you started to triage, and/or pull in other colleagues as needed. You can and should also move issues through the project board. You can set the status to "Backlog" (may be done at some point), "Todo" (should be done), "In Progress" (I am working on this), "In Review" (PR is open), or "Done". This helps -have an overview what is actively being worked on at any given time. +have an overview of what is actively being worked on at any given time. ### (Sentry Employees) How much time should be spent triaging? @@ -73,17 +73,17 @@ more time than this, bring this up with your manager to find ways to optimize th ### (Sentry Employees) What about "inoffical" triaging? -In addition to Github issues, you may also be pulled into triaging duty in other ways, e.g. via Discord or on Slack. +In addition to Github issues, you may also be pulled into triaging duty in other ways, e.g. via Discord , StackOverflow, GitHub Discussions, or Slack. -Generally, if non-trivial issues are raised this way, encourage the other parties to create issues on Github with as +Generally, if non-trivial issues are raised this way, encourage the other parties to create issues on GitHub with as much detail as possible, which also makes it easier for us to track the requests/issues. You should also include the -time youn spend working on such issues in your general triaging time. +time you spend working on such issues in your general triaging time. ### How to approach triaging an unknown issue? If you have no idea how to approach a given issue, there are a few general ways you could start: -1. Ask for a more thourough reproduction. Often, an issue does not contain enough information for us to figure out what +1. Ask for a more thorough reproduction. Often, an issue does not contain enough information for us to figure out what is going on. Feel free to ask liberally for more information, if the provided information is not enough. 2. Ask users to enable debug logs (`Sentry.intit({ debug: true })`), and paste the logs for their app. This can contain valuable information for debugging issues. From 7bd9e5f8b93b5564101e78bde5e319b76bc514f8 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Mon, 24 Jun 2024 09:52:42 +0200 Subject: [PATCH 3/3] small adjustments & pretter --- docs/triaging.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/triaging.md b/docs/triaging.md index c2b158dfdbcf..4343a0f1db50 100644 --- a/docs/triaging.md +++ b/docs/triaging.md @@ -4,15 +4,15 @@ The term _triage_ originally comes from medicine and describes the process of qu to a hospital in order to decide which ones are the most seriously ill and must be treated first. By _triaging issues_, we are evaluating problems that our customers are facing and providing the appropriate level of -support. The goal is to provide attention to all open issues, categorise them, and alert people when there are issues -of high severity. The goal is _not_ to fix all issues or answer all the questions coming from the open source community +support. The goal is to provide attention to all open issues, categorise them, and alert people when there are issues of +high severity. The goal is _not_ to fix all issues or answer all the questions coming from the open source community immediately. ## Bug fixing 101 Not every bug is equally critical or time sensitive. Some things reported as bugs aren’t even bugs. If you are unsure -whether something needs fixing, just reach out to your colleagues and get their opinion. When you do fix a bug, it should -always go hand-in-hand with adding new tests (or improving existing ones), so we can avoid any regressions in the +whether something needs fixing, just reach out to your colleagues and get their opinion. When you do fix a bug, it +should always go hand-in-hand with adding new tests (or improving existing ones), so we can avoid any regressions in the future. ## Triaging workflow @@ -56,12 +56,21 @@ future. When you start looking into an issue, you may assign the issue to yourself. This indicates to other colleagues that somebody else is already looking into the issue. Generally speaking, the first person to assign themselves/answer in the issue is considered the owner of this triaging issue, and other colleagues will generally not look into this issue -anymore unless prompted. Still, if you stumble upon an issue and you feel like you have something productive to add to the conversation, feel empowered to also comment on issues owned by somebody else. Make sure to follow up on issues you started to triage, and/or pull in other colleagues -as needed. +anymore unless prompted. Still, if you stumble upon an issue and you feel like you have something productive to add to +the conversation, feel empowered to also comment on issues owned by somebody else. Make sure to follow up on issues you +started to triage, and/or pull in other colleagues as needed. -You can and should also move issues through the project board. You can set the status to "Backlog" (may be done at some -point), "Todo" (should be done), "In Progress" (I am working on this), "In Review" (PR is open), or "Done". This helps -have an overview of what is actively being worked on at any given time. +If a team member is out of office, make sure that issues this person started to triage continue to receive attention. + +You can and should also move issues through the project board. You can set the status to: + +- `Backlog`: May be done at some point +- `Todo`: Should be done, feel free to pick up this issue any time +- `In Progress`: This is being worked on +- `In Review`: PR is open +- `Done` + +This helps have an overview of what is actively being worked on at any given time. ### (Sentry Employees) How much time should be spent triaging? @@ -73,7 +82,8 @@ more time than this, bring this up with your manager to find ways to optimize th ### (Sentry Employees) What about "inoffical" triaging? -In addition to Github issues, you may also be pulled into triaging duty in other ways, e.g. via Discord , StackOverflow, GitHub Discussions, or Slack. +In addition to Github issues, you may also be pulled into triaging duty in other ways, e.g. via Discord , StackOverflow, +GitHub Discussions, or Slack. Generally, if non-trivial issues are raised this way, encourage the other parties to create issues on GitHub with as much detail as possible, which also makes it easier for us to track the requests/issues. You should also include the