1# Triage issues 2 3The main goal of issue triage is to categorize all incoming Grafana issues and make sure each issue has all basic information needed for anyone else to understand and be able to start working on it. 4 5> **Note:** This information is for Grafana project Maintainers, Owners, and Admins. If you are a Contributor, then you will not be able to perform most of the tasks in this topic. 6 7The core maintainers of the Grafana project are responsible for categorizing all incoming issues and delegating any critical or important issue to other maintainers. Currently one maintainer each week is responsible. Besides that part, triage provides an important way to contribute to an open source project. 8 9Triage helps ensure issues resolve quickly by: 10 11- Ensuring the issue's intent and purpose is conveyed precisely. This is necessary because it can be difficult for an issue to explain how an end user experiences a problem and what actions they took. 12- Giving a contributor the information they need before they commit to resolving an issue. 13- Lowering the issue count by preventing duplicate issues. 14- Streamlining the development process by preventing duplicate discussions. 15 16If you don't have the knowledge or time to code, consider helping with triage. The community will thank you for saving them time by spending some of yours. 17 18## Simplified flowchart diagram of the issue triage process 19 20<!-- https://textik.com/#610afa78553def29 --> 21 22``` 23 +--------------------------+ 24 +----------------+ New issue opened/ | 25 | | more information added | 26 | +-------------+------------+ 27 | Ask for more | 28 | information +-------------+------------+ 29 | | All information needed | 30 | +--------+ to categorize the issue? +--------+ 31 | | | | | 32 | | NO +--------------------------+ YES | 33 | | | 34+------+-------+-------------+ +------------+---------+ +----------------------------+ 35| | | | | | 36| label: needs more info | | Needs investigation? +--YES---+ label: needs investigation | 37| | | | | | 38+----------------------------+ +----------------+-----+ +--------------+-------------+ 39 NO | | 40 | Investigate | 41 +-----------+----------+ | 42 | label: type/* | | 43 | label: area/* +------------------+ 44 | label: datasource/* | 45 +-----|----------+-----+ 46 | | 47 | | 48 | +--+--------------------+ +--------------------+ 49 | | | | label: priority/* | 50 | | Needs priority? +--YES---+| milestone? | 51 | | | | | 52 | +--------------------+--+ +----+---------------+ 53 | NO | | 54 | | | 55 +----+-------------+ +---+----------+ | 56 | | | | | 57 | Close issue +----------+ Done +------+ 58 | | | | 59 +------------------+ +--------------+ 60``` 61 62## 1. Find uncategorized issues 63 64To get started with issue triage and finding issues that haven't been triaged you have two alternatives. 65 66### Browse unlabeled issues 67 68The easiest and straight forward way of getting started and finding issues that haven't been triaged is to browse [unlabeled issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+no%3Alabel) and starting from the bottom and working yourself to the top. 69 70### Subscribe to all notifications 71 72The more advanced, but recommended way is to subscribe to all notifications from this repository which means that all new issues, pull requests, comments and important status changes are sent to your configured email address. Read this [guide](https://help.github.com/en/articles/watching-and-unwatching-repositories#watching-a-single-repository) for help with setting this up. 73 74It's highly recommended that you setup filters to automatically remove emails from the inbox and label/categorize them accordingly to make it easy for you to understand when you need to act upon a notification or where to look for finding issues that haven't been triaged etc. 75 76Instructions for setting up filters in Gmail can be found [here](#setting-up-gmail-filters). Another alternative is to use [Trailer](https://github.com/ptsochantaris/trailer) or similar software. 77 78## 2. Ensure the issue contains basic information 79 80Before triaging an issue very far, make sure that the issue's author provided the standard issue information. This will help you make an educated recommendation on how to categorize the issue. The Grafana project utilizes [GitHub issue templates](https://help.github.com/en/articles/creating-issue-templates-for-your-repository) to guide contributors to provide standard information that must be included for each type of template or type of issue. 81 82### Standard issue information that must be included 83 84Given a certain [issue template](<[template](https://github.com/grafana/grafana/issues/new/choose)>) have been used by the issue author or depending how the issue is perceived by the issue triage responsible, the following should help you understand what standard issue information that must be included. 85 86#### Bug reports 87 88Should explain what happened, what was expected and how to reproduce it together with any additional information that may help giving a complete picture of what happened such as screenshots, [query inspector](https://community.grafana.com/t/using-grafanas-query-inspector-to-troubleshoot-issues/2630) output and any environment related information that's applicable and/or maybe related to the reported problem: 89 90- Grafana version 91- Data source type & version 92- Platform & OS Grafana is installed on 93- User OS & Browser + versions 94- Using docker + what environment 95- Which plugins 96- Configuration database in use (sqlite, mysql, postgres) 97- Reverse proxy in front of Grafana, what version and configuration 98- Non-default configuration settings 99- Development environment like Go and Node versions, if applicable 100 101#### Enhancement requests 102 103Should explain what enhancement or feature that the author wants to be added and why that is needed. 104 105#### Accessibility issues 106 107This is a mix between a bug report and enhancement request but focused on accessibility issues to help make Grafana improve keyboard navigation, screen-reader support and being accessible to everyone. The report should include relevant WCAG criteria, if applicable. 108 109#### Support requests 110 111In general, if the issue description and title is perceived as a question no more information is needed. 112 113### Good practices 114 115To make it easier for everyone to understand and find issues they're searching for it's suggested as a general rule of thumbs to: 116 117- Make sure that issue titles are named to explain the subject of the issue, has a correct spelling and doesn't include irrelevant information and/or sensitive information. 118- Make sure that issue descriptions doesn't include irrelevant information, information from template that haven't been filled out and/or sensitive information. 119- Do your best effort to change title and description or request suggested changes by adding a comment. 120 121> **Note:** Above rules is applicable to both new and existing issues of the Grafana project. 122 123### Do you have all the information needed to categorize an issue? 124 125Depending on the issue, you might not feel all this information is needed. Use your best judgement. If you cannot triage an issue using what its author provided, explain kindly to the author that they must provide the above information to clarify the problem. Label issue with `needs more detail` and add any related `area/*` or `datasource/*` labels. 126 127If the author provides the standard information but you are still unable to triage the issue, request additional information. Do this kindly and politely because you are asking for more of the author's time. 128 129If the author does not respond to the requested information within the timespan of a week, close the issue with a kind note stating that the author can request for the issue to be reopened when the necessary information is provided. 130 131When you feel you have all the information needed you're ready to [categorizing the issue](#3-categorizing-an-issue). 132 133If you receive a notification with additional information provided but you are not anymore on issue triage and you feel you do not have time to handle it, you should delegate it to the current person on issue triage. 134 135## 3. Categorizing an issue 136 137An issue can have multiple of the following labels. Typically, a properly categorized issue should at least have: 138 139- One label identifying its type (`type/*`). 140- One or multiple labels identifying the functional areas of interest or component (`area/*`) and/or data source (`datasource/*`), if applicable. 141 142| Label | Description | 143| ------------------------ | ------------------------------------------------------------------------- | 144| `type/bug` | A feature isn't working as expected given design or documentation. | 145| `type/feature-request` | Request for a new feature or enhancement. | 146| `type/docs` | Documentation problem or enhancement. | 147| `type/accessibility` | Accessibility problem or enhancement. | 148| `type/question` | Issue is a question or is perceived as such. | 149| `type/duplicate` | An existing issue of the same subject/request have already been reported. | 150| `type/works-as-intended` | A reported bug works as intended/by design. | 151| `type/build-packaging` | Build or packaging problem or enhancement. | 152| `area/*` | Subject is related to a functional area of interest or component. | 153| `datasource/*` | Subject is related to a core data source plugin. | 154 155### Duplicate issues 156 157Make sure it's not a duplicate by searching existing issues using related terms from the issue title and description. If you think you know there is an existing issue, but can't find it, please reach out to one of the maintainers and ask for help. If you identify that the issue is a duplicate of an existing issue: 158 1591. Add a comment `/duplicate of #<issue number>`. GitHub will recognize this and add some additional context to the issue activity. 1602. The Grafana bot will do the rest, adding the correct label and closing comment 1613. Optionally add any related `area/*` or `datasource/*` labels. 162 163### Bug reports 164 165If it's not perfectly clear that it's an actual bug, quickly try to reproduce it. 166 167**It's a bug/it can be reproduced:** 168 1691. Add a comment describing detailed steps for how to reproduce it, if applicable. 1702. Label the issue `type/bug` and at least one `area/*` or `datasource/*` label. 1713. If you know that maintainers wont be able to put any resources into it for some time then label the issue with `help wanted` and optionally `beginner friendly` together with pointers on which code to update to fix the bug. This should signal to the community that we would appreciate any help we can get to resolve this. 1724. Move on to [prioritizing the issue](#4-prioritization-of-issues). 173 174**It can't be reproduced:** 175 1761. Either [ask for more information](#2-ensure-the-issue-contains-basic-information) needed to investigate it more thoroughly. 1772. Either [delegate further investigations](#investigation-of-issues) to someone else. 178 179**It works as intended/by design:** 180 1811. Kindly and politely add a comment explaining briefly why we think it works as intended and close the issue. 1822. Label the issue `type/works-as-intended`. 183 184### Enhancement/feature? 185 1861. Label the issue `type/feature-request` and at least one `area/*` or `datasource/*` label. 1872. Move on to [prioritizing the issue](#4-prioritization-of-issues). 188 189### Documentation issue? 190 191First, evaluate if the documentation makes sense to be included in the Grafana project: 192 193- Is this something we want/can maintain as a project? 194- Is this referring to usage of some specific integration/tool and in that case is that a popular use case in combination with Grafana? 195- If unsure, kindly and politely add a comment explaining that we would need [upvotes](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments) to identify that lots of other users want/need this. 196 197Second, label the issue `type/docs` and at least one `area/*` or `datasource/*` label. 198 199**Minor typo/error/lack of information:** 200 201There's a minor typo/error/lack of information that adds a lot of confusion for users and given the amount of work is a big win to make sure fixing it: 202 2031. Either update the documentation yourself and open a pull request. 2042. Either delegate the work to someone else by assigning that person to the issue and add the issue to next major/minor milestone. 205 206**Major error/lack of information:** 207 2081. Label the issue with `help wanted` and `beginner friendly`, if applicable, to signal that we find this important to fix and we would appreciate any help we can get from the community. 2092. Move on to [prioritizing the issue](#4-prioritization-of-issues). 210 211### Accessibility issues 212 2131. Label the issue `type/accessibility` and at least one `area/*` or `datasource/*` label. 214 215### Support requests 216 2171. Kindly and politely direct the issue author to the [community site](https://community.grafana.com/) and explain that GitHub is mainly used for tracking bugs and feature requests. If possible, it's usually a good idea to add some pointers to the issue author's question. 2182. Close the issue and label it with `type/question`. 219 220## 4. Prioritization of issues 221 222In general bugs and enhancement issues should be labeled with a priority. 223 224This is the most difficult thing with triaging issues since it requires a lot of knowledge, context and experience before being able to think of and start feel comfortable adding a certain priority label. 225 226The key here is asking for help and discuss issues to understand how more experienced project members think and reason. By doing that you learn more and eventually be more and more comfortable with prioritizing issues. 227 228In case there is an uncertainty around the prioritization of an issue, please ask the maintainers for help. 229 230| Label | Description | 231| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | 232| `priority/critical` | Highest priority. Must be actively worked on as someone's top priority right now. | 233| `priority/support-subscription` | This is important for one or several customers having a paid Grafana support subscription. | 234| `priority/important-soon` | Must be staffed and worked on either currently, or very soon, ideally in time for the next release. | 235| `priority/important-longterm` | Important over the long term, but may not be staffed and/or may need multiple releases to complete. | 236| `priority/nice-to-have` | It's a good idea, but not scheduled for any release. | 237| `priority/awaiting-more-evidence` | Lowest priority. Possibly useful, but not yet enough interest in it. | 238| `priority/unscheduled` | Something to look into before and to be discussed during the planning of the next (upcoming) major/minor stable release. | 239 240**Critical bugs** 241 2421. If a bug has been categorized and any of the following criteria apply, the bug should be labeled as critical and must be actively worked on as someone's top priority right now. 243 244 - Results in any data loss 245 - Critical security or performance issues 246 - Problem that makes a feature unusable 247 - Multiple users experience a severe problem affecting their business, users etc. 248 2492. Label the issue `priority/critical`. 2503. If applicable, label the issue `priority/support-subscription`. 2514. Add the issue to the next upcoming patch release milestone. Create a new milestone if there are none. 2525. Escalate the problem to the maintainers. 2536. Assign or ask a maintainer for help assigning someone to make this issue their top priority right now. 254 255**Important short-term** 256 2571. Label the issue `priority/important-soon`. 2582. If applicable, label the issue `priority/support-subscription`. 2593. Add the issue to the next upcoming patch or major/minor stable release milestone. Ask maintainers for help if unsure if it's a patch or not. Create a new milestone if there are none. 2604. Make sure to add the issue to a suitable backlog of a GitHub project and prioritize it or assign someone to work on it now or very soon. 2615. Consider requesting [help from the community](#5-requesting-help-from-the-community), even though it may be problematic given a short amount of time until it should be released. 262 263**Important long-term** 264 2651. Label the issue `priority/important-longterm`. 2662. Consider requesting [help from the community](#5-requesting-help-from-the-community). 267 268**Nice to have** 269 2701. Label the issue `priority/nice-to-have`. 2712. Consider requesting [help from the community](#5-requesting-help-from-the-community). 272 273**Not critical, but unsure?** 274 2751. Label the issue `priority/unscheduled`. 2762. Consider requesting [help from the community](#5-requesting-help-from-the-community). 277 278## 5. Requesting help from the community 279 280Depending on the issue and/or priority, it's always a good idea to consider signalling to the community that help from community is appreciated and needed in case an issue is not prioritized to be worked on by maintainers. Use your best judgement. In general, requesting help from the community means that a contribution has a good chance of getting accepted and merged. 281 282In many cases the issue author or community as a whole is more suitable to contribute changes since they're experts in their domain. It's also quite common that someone has tried to get something to work using the documentation without success and made an effort to get it to work and/or reached out to the [community site](https://community.grafana.com/) to get the missing information. Particularly in these areas it's more likely that there exist experts in their own domain and it is usually a good idea to request help from contributors: 283 284- Database setups 285- Authentication like OAuth providers and LDAP setups 286- Platform specific things 287- Reverse proxy setups 288- Alert notifiers 289 2901. Kindly and politely add a comment to signal to users subscribed to updates of the issue. 291 - Explain that the issue would be nice to get resolved, but it isn't prioritized to work on by maintainers for an unforeseen future. 292 - If possible or applicable, try to help contributors getting starting by adding pointers and references to what code/files need to be changed and/or ideas of a good way to solve/implement the issue. 2932. Label the issue with `help wanted`. 2943. If applicable, label the issue with `beginner friendly` to denote that the issue is suitable for a beginner to work on. 2954. If possible, try to estimate the amount of work by adding `effort/small`, `effort/medium` or `effort/large`. 296 297## Investigation of issues 298 299When an issue has all basic information provided, but the triage responsible haven't been able to reproduce the reported problem at a first glance, the issue is labeled [Needs investigation](https://github.com/grafana/grafana/labels/needs%20investigation). Depending on the perceived severity and/or number of [upvotes](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments), the investigation will either be delegated to another maintainer for further investigation or put on hold until someone else (maintainer or contributor) picks it up and eventually starts investigating it. 300 301Investigating issues can be a very time consuming task, especially for the maintainers, given the huge number of combinations of plugins, data sources, platforms, databases, browsers, tools, hardware, integrations, versions and cloud services, etc that are being used with Grafana. There is a certain number of combinations that are more common than others, and these are in general easier for maintainers to investigate. 302 303For some other combinations it may not be possible at all for a maintainer to setup a proper test environment to investigate the issue. In these cases we really appreciate any help we can get from the community. Otherwise the issue is highly likely to be closed. 304 305Even if you don't have the time or knowledge to investigate an issue we highly recommend that you [upvote](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments) the issue if you happen to have the same problem. If you have further details that may help investigating the issue please provide as much information as possible. 306 307## Automation 308 309We have some automation that triggers on comments or labels being added to issues. Many of these automated behaviors are defined in [commands.json](https://github.com/grafana/grafana/blob/main/.github/commands.json). Or in other [GitHub Actions](https://github.com/grafana/grafana/tree/main/.github/workflows) 310 311- Add /duplicate `#<issue number>` to have Grafana label & close issue with an appropriate message. 312- Add `bot/question` and the bot will close it with an appropriate message. 313 314[Read more on bot actions](https://github.com/grafana/grafana/blob/main/.github/bot.md) 315 316## External PRs 317 318Part of issue triage should also be triaging of external PRs. Main goal should be to make sure PRs from external contributors have an owner/reviewer and are not forgotten. 319 3201. Check new external PRs which do not have a reviewer. 3211. Check if there is a link to an existing issue. 3221. If not and you know which issue it is solving, add the link yourself, otherwise ask the author to link the issue or create one. 3231. Assign a reviewer based on who was handling the linked issue or what code or feature does the PR touches (look at who was the last to make changes there if all else fails). 324 325## Appendix 326 327### Setting up Gmail filters 328 329If you're using Gmail it's highly recommended that you setup filters to automatically remove email from the inbox and label them accordingly to make it easy for you to understand when you need to act upon a notification or process all incoming issues that haven't been triaged. 330 331This may be setup by personal preference, but here's a working configuration for reference. 332 3331. Follow instructions in [gist](https://gist.github.com/marefr/9167c2e31466f6316c1cba118874e74f) 3342. In Gmail, go to Settings -> Filters and Blocked Addresses 3353. Import filters -> select xml file -> Open file 3364. Review filters 3375. Optional, Check Apply new filters to existing email 3386. Create filters 339 340This will give you a structure of labels in the sidebar similar to the following: 341 342``` 343 - Inbox 344 ... 345 - GitHub (mine) 346 - activity 347 - assigned 348 - mentions 349 - GitHub (other) 350 - Grafana 351``` 352 353- All notifications you’ll need to read/take action on show up as unread in GitHub (mine) and its sub-labels. 354- All other notifications you don’t need to take action on show up as unread in GitHub (other) and its sub-labels 355 - This is convenient for issue triage and to follow the activity in the Grafana project. 356