ISSUE_TRIAGE.md
Triaging of issues
Grafana being a popular open source project there are a lot of incoming issues. The main goal of issue triage is to categorize all incoming issues and make sure it has all basic information needed for anyone else to understand and/or being able to start working with it.
The core maintainers of the Grafana project is responsible for categorizing all incoming issues and delegate any critical and/or important issue to other maintainers. Currently there's one maintainer each week responsible. Besides that part, triage provides an important way to contribute to an open source project. Triage helps ensure issues resolve quickly by:
- Describing 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.
- Giving a contributor the information they need before they commit to resolving an issue.
- Lowering the issue count by preventing duplicate issues.
- Streamlining the development process by preventing duplicate discussions.
- If 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.
Simplified flowchart diagram of the issue triage process:
+--------------------------+
+----------------+ New issue opened/ |
| | more information added |
| +-------------+------------+
| Ask for more |
| information +-------------+------------+
| | All information needed |
| +--------+ to categorize the issue? +--------+
| | | | |
| | NO +--------------------------+ YES |
| | |
+------+-------+-------------+ +------------+---------+ +----------------------------+
| | | | | |
| label: needs more details | | Needs investigation? +--YES---+ label: needs investigation |
| | | | | |
+----------------------------+ +----------------+-----+ +--------------+-------------+
NO | |
| Investigate |
+-----------+----------+ |
| label: type/* | |
| label: area/* +------------------+
| label: datasource/* |
+-----|----------+-----+
| |
| |
| +--+--------------------+ +--------------------+
| | | | label: priority/* |
| | Needs priority? +--YES---+| milestone? |
| | | | |
| +--------------------+--+ +----+---------------+
| NO | |
| | |
+----+-------------+ +---+----------+ |
| | | | |
| Close issue +----------+ Done +------+
| | | |
+------------------+ +--------------+How you can help
There are multiple ways that you can help with the Grafana project, especially without writing a single line of code. Everyone in the Grafana community will be greatly thankful you for helping out with any of the below tasks.
Answer/ask questions
The community site is the main channel to be used for asking and answering questions related to the Grafana project. This may be the first place a new or existing Grafana user look/ask for help after they found that the documentation wasn't answering their questions. It's very important to help new and existing users so that these new users can find proper answers and eventually help out other users and by that keep growing the Grafana community.
Please signup to the Grafana community site and start help other Grafana users by answering their questions and/or ask for help.
Report documentation enhancements
If you visit the documentation site and find typos/error/lack of information please report these by clicking on the Request doc changes link found on every page and/or contribute the changes yourself by clicking on Edit this page and open a pull request. Everyone in the community will greatly thank you for.
Please read about how documentation issues is triaged below to understand what kind of documentation may be suitable to request/add.
Report a security vulnerability
Please review the security policy for more details.
Report bugs
Report a bug you found when using Grafana by opening a new bug report.
Request enhancements/new features
Suggest an enhancement or new feature for the Grafana project by opening a new enhancement issue.
Alternatively, help make Grafana be better at being accessible to all by opening a new accessibility issue.
Report inaccurate issue information
If you find an issue that have a badly formatted title and/or description, bad language/grammar and/or wrong labels it's important to let the issue author or maintainers know so it can be fixed. See good practices regarding basic information for issues below.
Request closing of issues
The Grafana project have a lot of open issues and the main goal is to only have issues open if their still relevant. If you find an issue that you think already have been resolved or no longer is relevant please report by adding a comment and explain why you think it should be closed including related issues (#<issue number>), if applicable, and optionally mention one of the maintainers.
Investigate issues
Vote on enhancements/bugs
Helping the Grafana project to know which issues are most important by users and the community is crucial for the success of the project. Read more about prioritizing issues for details about how issues are being prioritized. The Grafana project use GitGub issues and reactions for collecting votes on enhancement and bugs.
Please don't add +1 issue comments or similar since that will notify everyone that have subscribed to an issue and it doesn't add any useful update, rather it creates a bad .
If you want to show your interest or importance of an issue, please use GitHub's reactions.
Report duplicates
If you find two issues describing the same bug/enhancement/feature please add a comment in one of the issue and explain which issues (#<issue number>) you think is a duplicate of another issue (#<issue number>).
Suggest ideas for resolving bugs/enhancements
Related to how issues are being prioritized it's important to help anyone that's interested in contributing code for resolving a bug or enhancement. This can be anything from getting started and setup the development environment to reference code and files where changes probably needs to be made and/or suggest ideas on how enhancements may function/be implemented.
Please read about how help from the community may be requested when issues being triaged.
1. Find uncategorized issues
To get started with issue triage and finding issues that haven't been triaged you have two alternatives.
Browse unlabeled issues
The easiest and straigt forward way of getting started and finding issues that haven't been triaged is to browse unlabeled issues and starting from the bottom and working yourself to the top.
Subscribe to all notifications
The 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 for help with setting this up.
It'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.
Instructions for setting up filters in Gmail can be found here. Another alternative is to use Trailer or similar software.
2. Ensure the issue contains basic information
Before 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 to guide contributors to provide standard information that must be included for each type of template or type of issue.
Standard issue information that must be included
Given a certain issue template 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.
Bug report?
Should 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 output and any environment related information that's applicable and/or maybe related to the reported problem:
- Grafana version
- Data source type & version
- Platform & OS Grafana is installed on
- User OS & Browser + versions
- Using docker + what environment
- Which plugins
- Configuration database in use (sqlite, mysql, postgres)
- Reverse proxy in front of Grafana, what version and configuration
- Non-default configuration settings
- Development environment like Go and Node versions, if applicable
Enhancement request?
Should explain what enhancement or feature that the author wants to be added and why that is needed.
Accessibility issue?
This 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.
Support request?
In general, if the issue description and title is perceived as a question no more information is needed.
Good practices
To make it easier for everyone to understand and find issues they're searching for it's suggested as a general rule of thumbs to:
- 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.
- Make sure that issue descriptions doesn't include irrelevant information, information from template that haven't been filled out and/or sensitive information.
- Do your best effort to change title and description or request suggested changes by adding a comment.