IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-01-24 15:27:01 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Edit of "ISSUE_TRIAGE" and other topics (part 3 of doc quality project) (#88106)

Browse Source 
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
Joseph Perez 2024-05-31 00:31:53 -07:00 committed by GitHub
parent ba4c1fcf76
commit 9d8052830f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 204 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

274
contribute/ISSUE_TRIAGE.md
View File

@ -1,20 +1,11 @@
# Triage issues
The 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.
The main goal of issue triage is to categorize all incoming Grafana issues and make sure each issue has all the essential information needed for anyone to understand and be able to start working on it.
> **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.
> **Note:** This information is for Grafana project Maintainers, Owners, and Admins. If you are a Contributor, then you won't be able to perform most of the tasks in this topic.
The 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.
Triage helps ensure issues resolve quickly by:
- 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.
- 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
<!-- https://textik.com/#610afa78553def29 -->
@ -68,33 +59,44 @@ If you don't have the knowledge or time to code, consider helping with triage. T
```
## 1. Find uncategorized issues
## Key functions of issue triage
Triage helps ensure issues resolve quickly by:
- 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.
- 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.
### 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
#### Browse unlabeled issues
The 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.
The easiest and most straightforward 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 then work on them starting from the bottom to the top.
### Subscribe to all notifications
#### 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](https://help.github.com/en/articles/watching-and-unwatching-repositories#watching-a-single-repository) 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.
It's highly recommended that you set up filters to automatically remove emails from the inbox and label them accordingly. When issues are properly categorized you can easily understand when you need to act upon a notification or where to look to find issues that haven't been triaged.
Instructions 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.
## 2. Ensure the issue contains basic information
### 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](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-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.
Before triaging an issue very far, make sure that the issue's author provided the standard information. This helps you make an educated recommendation on how to categorize the issue. The Grafana project uses [GitHub issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-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.
### Standard issue information that must be included
#### Standard issue information that must be included
Given a certain [issue 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.
Grafana uses various [issue templates](https://github.com/grafana/grafana/issues/new/choose) to collect information from the issue reporter. The following list describes the standard information that is included.
#### Bug reports
##### Bug reports
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](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:
Bug reports should explain what happened, what was expected, and how to reproduce it. Also, it should include 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 relevant information about the environment. For example:
- Grafana version:
- Data source type & version:
@ -103,250 +105,249 @@ Should explain what happened, what was expected and how to reproduce it together
- Grafana plugins:
- Others:
#### Enhancement requests
##### Enhancement requests
Prior to August, 2023, community-submitted feature requests were submitted as [Github discussions](https://github.com/grafana/grafana/discussions). These are now submitted using the [feature request issue template](https://github.com/grafana/grafana/issues/new?assignees=&labels=type%2Ffeature-request&projects=&template=1-feature_requests.md).
> **Note:** Prior to August, 2023, community-submitted feature requests were submitted as [Github discussions](https://github.com/grafana/grafana/discussions). These are now submitted using the [feature request issue template](https://github.com/grafana/grafana/issues/new?assignees=&labels=type%2Ffeature-request&projects=&template=1-feature_requests.md).
When submitting an enhancement request we ask that users focus on the problem they'd like to solve and why it’s a problem rather than focusing on the solution itself. To facilitate this the feature requests template includes the following:
When submitting an enhancement request we ask that users focus on the problem they'd like to solve and why it’s a problem rather than focusing on the solution itself. To facilitate these objectives, the feature requests template includes the following:
- What would you like to be added?:
- Why is this needed (describe your use case and goals)\*\*?:
#### Accessibility issues
##### Accessibility issues
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](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0), if applicable.
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 general accessibility. The report should include relevant [WCAG criteria](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0), if applicable.
Grafana Labs is dedicated to improving our graphical user interfaces and overall experience so that our product becomes usable and accessible for people with disabilities as well as anyone else. Learn more about Grafana's commitment to [A11y](https://grafana.com/accessibility/) (accessibility).
#### Support requests
##### Support requests
In general, if the issue description and title is perceived as a question no more information is needed. See how to categorize these requests [here](#support-requests-1).
### Good practices
#### 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:
To make it easier for everyone to understand and find issues a good rule of thumbs is 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.
- Make sure that issue titles are named to explain the subject of the issue, are spelled correctly, and don't include irrelevant or sensitive information.
- Make sure that issue descriptions don't include irrelevant information, information from a template that hasn't been filled out, or sensitive information.
- Do your best effort to change the title and description or request suggested changes by adding a comment.
> **Note:** Above rules is applicable to both new and existing issues of the Grafana project.
#### Do you have all the information needed to categorize an issue?
### Do you have all the information needed to categorize an issue?
Depending 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 info` and add any related `area/*` or `datasource/*` labels. Alternatively, use `bot/needs more info` label and the Grafana bot will request it for you.
Depending 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 previously mentioned information to clarify the problem. Label issue with `needs more info` and add any related `area/*` or `datasource/*` labels. Alternatively, use `bot/needs more info` label and the Grafana bot will request it for you.
If 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.
If 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.
If the author does not respond to the requested information within 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.
When you feel you have all the information needed you're ready to [categorizing the issue](#3-categorizing-an-issue).
When you feel you have all the information needed, then you're ready to [categorize the issue](#3-categorize-an-issue).
If 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.
If you receive a notification with additional information provided, but you aren't on issue triage anymore and you feel you don't have time to handle it, you should delegate it to the current person on issue triage.
## 3. Categorizing an issue
### 3. Categorize an issue
An issue can have multiple of the following labels. Typically, a properly categorized issue should at least have:
An issue can have multiple labels. Typically, a properly categorized issue should at least have these labels:
- One label identifying its type (`type/*`).
- One or multiple labels identifying the functional areas of interest or component (`area/*`) and/or data source (`datasource/*`), if applicable.
| Label | Description |
| ------------------------ | ------------------------------------------------------------------------- |
| `type/bug` | A feature isn't working as expected given design or documentation. |
| `type/feature-request` | Request for a new feature or enhancement. |
| `type/docs` | Documentation problem or enhancement. |
| `type/accessibility` | Accessibility problem or enhancement. |
| `type/question` | Issue is a question or is perceived as such. |
| `type/duplicate` | An existing issue of the same subject/request have already been reported. |
| `type/works-as-intended` | A reported bug works as intended/by design. |
| `type/build-packaging` | Build or packaging problem or enhancement. |
| `area/*` | Subject is related to a functional area of interest or component. |
| `datasource/*` | Subject is related to a core data source plugin. |
| Label | Description |
| ------------------------ | ------------------------------------------------------------------- |
| `type/bug` | A feature isn't working as expected given design, or documentation. |
| `type/feature-request` | Request for a new feature, or enhancement. |
| `type/docs` | Documentation problem, or enhancement. |
| `type/accessibility` | Accessibility problem, or enhancement. |
| `type/question` | Issue is a question or is perceived as such. |
| `type/duplicate` | An existing issue of the same subject has already been reported. |
| `type/works-as-intended` | A reported bug works as intended (that is, by design). |
| `type/build-packaging` | Build or packaging problem, or enhancement. |
| `area/*` | Subject is related to a functional area of interest, or component. |
| `datasource/*` | Subject is related to a core data source plugin. |
### Duplicate issues
#### Duplicate issues
Make 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:
1. Add a comment `/duplicate of #<issue number>`. GitHub will recognize this and add some additional context to the issue activity.
2. The Grafana bot will do the rest, adding the correct label and closing comment
3. Add `type/duplicate` label. Optionally add any related `area/*` or `datasource/*` labels.
1. The Grafana bot will do the rest, adding the correct label and a closing comment.
1. Add the `type/duplicate` label. Optionally, you may add any related `area/*` or `datasource/*` labels.
### Bug reports
#### Bug reports
If it's not perfectly clear that it's an actual bug, quickly try to reproduce it.
**It's a bug/it can be reproduced:**
**It can be reproduced:**
1. Add a comment describing detailed steps for how to reproduce it, if applicable.
2. Label the issue `type/bug` and at least one `area/*` or `datasource/*` label.
3. If you know that maintainers won't 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.
4. Move on to [prioritizing the issue](#4-prioritization-of-issues).
1. Label the issue `type/bug` and at least one `area/*` or `datasource/*` label.
1. If you know that maintainers won't 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.
1. Move on to [prioritizing the issue](#4-prioritization-of-issues).
**It can't be reproduced:**
1. Either [ask for more information](#2-ensure-the-issue-contains-basic-information) needed to investigate it more thoroughly.
2. Either [delegate further investigations](#investigation-of-issues) to someone else.
1. Either [delegate further investigations](#investigation-of-issues) to someone else.
**It works as intended/by design:**
**It works as intended (that is, by design):**
1. Kindly and politely add a comment explaining briefly why we think it works as intended and close the issue.
2. Label the issue `type/works-as-intended`.
1. Label the issue `type/works-as-intended`.
### Enhancement/feature?
#### Enhancement or feature request?
1. Label the issue `type/feature-request` and add at least one `area/*` or `datasource/*` label.
2. Make sure the submitter has justified why this feature requests is important.
1. Make sure the submitter has justified why this feature requests is important.
### Documentation issue?
#### Documentation issue?
First, evaluate if the documentation makes sense to be included in the Grafana project:
- Is this something we want/can maintain as a project?
- Is this referring to usage of some specific integration/tool and in that case is that a popular use case in combination with Grafana?
- If unsure, kindly and politely add a comment explaining that we would need [upvotes](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments) to identify that lots of other users want/need this.
- Is this something we want and can maintain as a project?
- Is this referring to usage of some specific integration and in that case is that a popular use case in combination with Grafana?
- If unsure, kindly and politely add a comment explaining that we would need [upvotes](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments) to identify that lots of other users want or need this.
Second, label the issue `type/docs` and at least one `area/*` or `datasource/*` label.
**Minor typo/error/lack of information:**
There'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:
There's a minor typo, error, or lack of information that adds a lot of confusion for users and is a big win to fix it:
1. Either update the documentation yourself and open a pull request.
2. Either delegate the work to someone else by assigning that person to the issue and add the issue to next major/minor milestone.
1. Either delegate the work to someone else by assigning that person to the issue. Note that the milestone is automatically assigned and usually doesn't need to be manually edited.
**Major error/lack of information:**
1. 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.
2. Move on to [prioritizing the issue](#4-prioritization-of-issues).
1. Move on to [prioritizing the issue](#4-prioritization-of-issues).
### Accessibility issues
#### Accessibility issues
1. Label the issue `type/accessibility` and at least one `area/*` or `datasource/*` label.
### Support requests
#### Support requests
1. 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.
2. Label the issue with `bot/question`. The Grafana bot will automatically close the issue, and it will add the type/question label for you.
1. Label the issue with `bot/question`. The Grafana bot will automatically close the issue, and it will add the type/question label for you.
## 4. Prioritization of issues
### 4. Prioritization of issues
In general bugs and enhancement issues should be labeled with a priority.
In general, bugs and enhancement issues should be labeled with a priority.
This 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.
This is the most difficult thing with triaging issues since it requires a lot of knowledge, context and experience before it is possible to skillfully add a specific priority label.
The 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.
The key here is to ask 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.
In case there is an uncertainty around the prioritization of an issue, please ask the maintainers for help.
| Label | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `priority/critical` | Highest priority. Must be actively worked on as someone's top priority right now. |
| `priority/support-subscription` | This is important for one or several customers having a paid Grafana support subscription. |
| `priority/important-soon` | Must be staffed and worked on either currently, or very soon, ideally in time for the next release. |
| `priority/important-longterm` | Important over the long term, but may not be staffed and/or may need multiple releases to complete. |
| `priority/nice-to-have` | It's a good idea, but not scheduled for any release. |
| `priority/awaiting-more-evidence` | Lowest priority. Possibly useful, but not yet enough interest in it. |
| `priority/unscheduled` | Something to look into before and to be discussed during the planning of the next (upcoming) major/minor stable release. |
| Label | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `priority/critical` | Highest priority. Must be actively worked on as someone's top priority right now. |
| `priority/support-subscription` | This is important for one or several customers having a paid Grafana support subscription. |
| `priority/important-soon` | Must be staffed and worked on either currently, or very soon, ideally in time for the next release. |
| `priority/important-longterm` | Important over the long term, but may need multiple releases to complete. |
| `priority/nice-to-have` | It's a good idea, but not scheduled for any release. |
| `priority/awaiting-more-evidence` | Lowest priority. Possibly useful, but not yet enough interest in it. |
| `priority/unscheduled` | Something to look into before and to be discussed during the planning of the next major/minor stable release. |
**Critical bugs**
1. 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.
1. 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:
- Results in any data loss
- Critical security or performance issues
- Problem that makes a feature unusable
- Multiple users experience a severe problem affecting their business, users etc.
- Multiple users experience a severe problem affecting their business, user experience, and so on.
2. Label the issue `priority/critical`.
3. If applicable, label the issue `priority/support-subscription`.
4. Add the issue to the next upcoming patch release milestone. Create a new milestone if there are none.
5. Escalate the problem to the maintainers.
6. Assign or ask a maintainer for help assigning someone to make this issue their top priority right now.
1. Label the issue `priority/critical`.
1. If applicable, label the issue `priority/support-subscription`.
1. Add the issue to the next upcoming patch release milestone. Create a new milestone if there are none.
1. Escalate the problem to the maintainers.
1. Assign or ask a maintainer for help assigning someone to make this issue their top priority right now.
**Important short-term**
1. Label the issue `priority/important-soon`.
2. If applicable, label the issue `priority/support-subscription`.
3. 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.
4. 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.
5. 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.
1. If applicable, label the issue `priority/support-subscription`.
1. 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.
1. 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.
1. 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.
**Important long-term**
1. Label the issue `priority/important-longterm`.
2. Consider requesting [help from the community](#5-requesting-help-from-the-community).
1. Consider requesting [help from the community](#5-requesting-help-from-the-community).
**Nice to have**
1. Label the issue `priority/nice-to-have`.
2. Consider requesting [help from the community](#5-requesting-help-from-the-community).
1. Consider requesting [help from the community](#5-requesting-help-from-the-community).
**Not critical, but unsure?**
1. Label the issue `priority/unscheduled`.
2. Consider requesting [help from the community](#5-requesting-help-from-the-community).
1. Consider requesting [help from the community](#5-request-help-from-the-community).
## 5. Requesting help from the community
### 5. Request help from the community
Depending 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.
It's generally a good idea to consider signaling to the community that help is appreciated and needed in case an issue isn't 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.
In 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:
In 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, made an effort to get it to work, reached out to the [community site](https://community.grafana.com/) to get the missing information, or some combination of these things.
In certain areas there probably exist domain experts who may be able to help:
- Database setups
- Authentication like OAuth providers and LDAP setups
- Platform specific things
- Platform-specific things
- Reverse proxy setups
- Alert notifiers
1. Kindly and politely add a comment to signal to users subscribed to updates of the issue.
- Explain that the issue would be nice to get resolved, but it isn't prioritized to work on by maintainers for an unforeseen future.
- 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.
2. Label the issue with `help wanted`.
3. If applicable, label the issue with `beginner friendly` to denote that the issue is suitable for a beginner to work on.
4. If possible, try to estimate the amount of work by adding `effort/small`, `effort/medium` or `effort/large`.
- If possible or applicable, try to help contributors getting starting by adding pointers and references to what code needs to be changed. Note any suggests for good ways of solving or implementing the issue.
1. Label the issue with `help wanted`.
1. If applicable, label the issue with `beginner friendly` to denote that the issue is suitable for a beginner to work on.
1. If possible, try to estimate the amount of work by adding `effort/small`, `effort/medium` or `effort/large`.
## Investigation of issues
### Investigation of issues
When 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 [`triage/needs-confirmation`](https://github.com/grafana/grafana/labels/triage%2Fneeds-confirmation). Depending on the perceived severity and/or number of [upvotes](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-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.
When an issue has all basic information provided, but the triage responsible hasn't been able to reproduce the reported problem at a first glance, the issue is labeled [`triage/needs-confirmation`](https://github.com/grafana/grafana/labels/triage%2Fneeds-confirmation). Depending on the perceived severity and/or number of [upvotes](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-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.
Investigating 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.
Investigating 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, hardware, integrations, cloud services, and so on, that are used with Grafana. There are a certain number of combinations that are more common than others, and these are in general easier for maintainers to investigate.
For 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.
Even if you don't have the time or knowledge to investigate an issue we highly recommend that you [upvote](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-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.
Even if you don't have the time or knowledge to investigate an issue we highly recommend that you [upvote](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-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.
## Automation
### Automation
We 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)
[Read more on bot actions](https://github.com/grafana/grafana/blob/main/.github/bot.md)
To learn more about bot actions, refer to our [bot documentation](https://github.com/grafana/grafana/blob/main/.github/bot.md).
## External PRs
### External PRs
Part 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.
Part of issue triage should also be triaging of external PRs. The main goal should be to make sure PRs from external contributors have an owner and aren't forgotten.
1. Check new external PRs which do not have a reviewer. You can easily search for pull requests made by external contributors by using the label: `pr/external` in your [query search](https://github.com/grafana/grafana/pulls?q=is%3Aopen+is%3Apr+label%3Apr%2Fexternal) Note: external PRs are automatically labeled with `pr/external` upon creation.
2. Check if there is a link to an existing issue. The link to a existing issue should be in the description section, underneath “Which issue(s) does this PR fix?:”.
3. 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.
4. 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).
1. Check new external PRs which don't have a reviewer. You can easily search for pull requests made by external contributors by using the label: `pr/external` in your [query search](https://github.com/grafana/grafana/pulls?q=is%3Aopen+is%3Apr+label%3Apr%2Fexternal) Note: external PRs are automatically labeled with `pr/external` upon creation.
1. Check if there is a link to an existing issue. The link to a existing issue should be in the description section, underneath “Which issue(s) does this PR fix?:”. 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.
1. Assign a reviewer based on who was handling the linked issue or what code or feature the PR touches (if all else fails, look at who was the last to make changes).
## Appendix
### Appendix
### Setting up Gmail filters
#### Setting up Gmail filters
If 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.
If you're using Gmail, a best practice is to set up filters to automatically remove emails from the inbox and label them to make it easy for you to understand when you need to act upon a notification. You should be able to promptly process all incoming issues that haven't been triaged.
This may be setup by personal preference, but here's a working configuration for reference.
This may be set up by personal preference, but here's a working configuration for reference:
1. Follow instructions in [gist](https://gist.github.com/marefr/9167c2e31466f6316c1cba118874e74f)
2. In Gmail, go to Settings -> Filters and Blocked Addresses
3. Import filters -> select xml file -> Open file
4. Review filters
5. Optional, Check Apply new filters to existing email
6. Create filters
1. In Gmail, go to **Settings** -> **Filters and Blocked Addresses**.
1. On the menu, select **Import filters**, then select and open the XML file.
1. Review the filters.
1. Optional: Select **Apply new filters to existing email**.
1. Create filters.
This will give you a structure of labels in the sidebar similar to the following:
This gives you a structure of labels in the sidebar similar to the following:
```
- Inbox
@ -359,6 +360,5 @@ This will give you a structure of labels in the sidebar similar to the following
- Grafana
```
- All notifications you’ll need to read/take action on show up as unread in GitHub (mine) and its sub-labels.
- All other notifications you don’t need to take action on show up as unread in GitHub (other) and its sub-labels
- This is convenient for issue triage and to follow the activity in the Grafana project.
- All notifications you’ll need to take action on should show up as unread in **GitHub (mine)** and its sub-labels.
- All notifications you don’t need to take action on show up as unread in **GitHub (other)** and its sub-labels.

32
contribute/UPGRADING_DEPENDENCIES.md
View File

@ -1,6 +1,6 @@
# Guide to upgrading dependencies
Upgrading Go or Node.js requires making changes in many different files. See below for a list and explanation for each.
Upgrading Go or Node.js requires making changes in many different files. Refer to the following list for more information.
## Go
@ -19,7 +19,7 @@ Upgrading Go or Node.js requires making changes in many different files. See bel
## Go dependencies
The Grafana project uses [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies on external packages. This requires a working Go environment with version 1.11 or greater installed.
The Grafana project uses [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies on external packages. This requires a working Go environment with version 1.11 or later installed.
To add or update a new dependency, use the `go get` command:
@ -36,17 +36,19 @@ Tidy up the `go.mod` and `go.sum` files:
go mod tidy
```
You have to commit the changes to `go.mod` and `go.sum` before submitting the pull request.
You have to commit the changes to `go.mod` and `go.sum` before you submit the pull request.
To understand what the actual dependencies of `grafana-server` are, one could run it with `-vv` flag. This might produce an output, different from `go.mod` contents and `-vv` option is the source of truth here. It lists the modules _compiled_ into the executable, while `go.mod` lists also test and weak transitive dependencies (modules, used in some package, which is not in use by itself). If you are interested in reporting a vulnerability in a dependency module - please consult `-vv` output, maybe the "dependency" is not a dependency as such.
To understand what the actual dependencies of `grafana-server` are, you can run it with the `-vv` flag. Note that this command might produce an output different from `go.mod` contents, and `-vv` option is the source of truth here. The output lists the modules _compiled_ into the executable, whereas `go.mod` lists also test and weak transitive dependencies (that is, modules, used in some packages, which aren't in use by itself). If you're interested in reporting a vulnerability in a dependency module, consult the `-vv` output, maybe the "dependency" isn't actually a dependency as such.
### Upgrading dependencies
If you need to upgrade a direct or indirect dependency, you can do it like so, $MODULE being the dependency in question: `go get -u $MODULE`. The corresponding entry in go.mod should then have the version you specified; if it's an indirect dependency, the entry should have the `// indirect` comment. Follow this by executing `go mod tidy`, to ensure that go.mod and go.sum are up to date. If the indirect dependency turns out to not be used (transitively) by any of our packages, `go mod tidy` will actually strip it from go.mod. In that case, you can just ignore it since it isn't used in the end.
If you need to upgrade a direct or indirect dependency, you can do it like so, where _`MODULE`_ is the dependency in question: `go get -u <MODULE>`. The corresponding entry in `go.mod` should then have the version you specified. If it's an indirect dependency, the entry should have the `// indirect` comment.
To do so, execute `go mod tidy` to ensure that `go.mod` and `go.sum` are updated. If the indirect dependency turns out to not be used (transitively) by any of our packages, `go mod tidy` actually strips it from `go.mod`. In that case, you can just ignore it because ultimately it isn't used.
## Node.js dependencies
Updated using `yarn`.
Updated using `yarn`:
- `package.json`
@ -62,26 +64,26 @@ Our CI builds run on Drone.
#### Dependencies
- nodejs
- golang
- grafana/build-container (our custom docker build container)
- Node.js
- Go
- `grafana/build-container` (our custom Docker build container)
### grafana/build-container
The main build steps (in Drone) happen using a custom Docker image that comes pre-baked with some of the necessary dependencies.
Link: [grafana/build-container](https://github.com/grafana/grafana/tree/main/scripts/build/ci-build)
Link: [`grafana/build-container`](https://github.com/grafana/grafana/tree/main/scripts/build/ci-build)
#### Dependencies
- fpm
- nodejs
- golang
- crosscompiling (several compilers)
- Node.js
- Go
- cross-compiling (several compilers)
### Appveyor
Main and release builds trigger test runs on Appveyors build environment so that tests will run on Windows.
Main and release builds trigger test runs on the Appveyors build environment so that tests will run on Windows.
#### Files:
@ -107,4 +109,4 @@ There is a Docker build for Grafana in the root of the project that allows anyon
### Local developer environments
Please send out a notice in the grafana-dev slack channel when updating Go or Node.js to make it easier for everyone to update their local developer environments.
It is a good practice to send out a notice in the grafana-dev Slack channel when updating Go or Node.js to make it easier for everyone to update their local developer environments.

99
contribute/internationalization.md
View File

@ -2,22 +2,22 @@
Grafana uses the [i18next](https://www.i18next.com/) framework for managing translating phrases in the Grafana frontend.
## tl;dr
## TL;DR
**Please note:** We do not currently accept contributions for translations. Please do not submit pull requests translating grafana.json files - they will be rejected. We do accept contributions to mark up phrases for translation.
**Note:** We don't currently accept contributions for translations. Please don't submit pull requests translating `grafana.json` files - they will be rejected. We do accept contributions to mark up phrases for translation.
- Use `<Trans i18nKey="search-results.panel-link">Go to {{ pageTitle }}</Trans>` in code to add a translatable phrase
- Translations are stored in JSON files in `public/locales/{locale}/grafana.json`
- If a particular phrase is not available in the a language then it will fall back to English
- To update phrases in English, edit the default phrase in the component's source and then run `make i18n-extract`.
- The single source of truth for en-US (fallback language) is in grafana/grafana, the single source of truth for any translated language is Crowdin
- Use `<Trans i18nKey="search-results.panel-link">Go to {{ pageTitle }}</Trans>` in code to add a translatable phrase.
- Translations are stored in JSON files in `public/locales/{locale}/grafana.json`.
- If a particular phrase isn't available in a given language, then it will fall back to English.
- To update phrases in English, edit the default phrase in the component's source, and then run `make i18n-extract`.
- The single source of truth for `en-US` (fallback language) is in `grafana/grafana`, and the single source of truth for any translated language is Crowdin.
- To update phrases in any translated language, edit the phrase in Crowdin. Do not edit the `{locale}/grafana.json`
## How to add a new translation phrase
### JSX
1. For JSX children, use the `<Trans />` component from `app/core/internationalization` with the `i18nKey`, ensuring it conforms to the guidelines below, with the default english translation. e.g.
1. For JSX children, use the `<Trans />` component from `app/core/internationalization` with the `i18nKey`, ensuring it conforms to the following guidelines, with the default English translation. For example:
```jsx
import { Trans } from 'app/core/internationalization';
@ -29,20 +29,20 @@ const SearchTitle = ({ term }) => (
);
```
Prefer using `<Trans />` for JSX children, and `t()` for props and other javascript usage.
Prefer using `<Trans />` for JSX children, and `t()` for props and other JavaScript usage.
When translating in grafana-ui, use a relative path to import `<Trans />` and `t()` from `src/utils/i18n`.
When translating in `grafana-ui`, use a relative path to import `<Trans />` and `t()` from `src/utils/i18n`.
Note that our tooling must be able to statically analyse the code to extract the phrase, so the `i18nKey` can not be dynamic. e.g. the following will not work:
Note that our tooling must be able to statically analyze the code to extract the phrase, so the `i18nKey` can't be dynamic. For example: the following will not work:
```jsx
const ErrorMessage = ({ id, message }) => <Trans i18nKey={`errors.${id}`}>There was an error: {{ message }}</Trans>;
```
2. Upon reload, the default English phrase will appear on the page.
2. Upon reload, the default English phrase appears on the page.
3. Before submitting your PR, run the `make i18n-extract` command to extract the messages you added into the `public/locales/en-US/grafana.json` file and make them available for translation.
**Note:** All other languages will receive their translations when they are ready to be downloaded from Crowdin.
**Note:** All other languages receive their translations when they are ready to be downloaded from Crowdin.
### Plain JS usage
@ -62,38 +62,40 @@ Interpolating phrases is a bit more verbose. Make sure the placeholders in the s
const placeholder = t('page.greeting', 'Hello {{ username }}', { username });
```
While the `t` function can technically be used outside of React functions (e.g, in actions/reducers), aim to keep all UI phrases within the React UI functions.
While the `t` function can technically be used outside of React functions (for example, in actions or reducers), aim to keep all UI phrases within the React UI functions.
## How to add a new language
1. Add a new locale in Crowdin
1. Grafana OSS Crowdin project
2. "dot dot dot" menu in top right
3. Target languages, and add the language
4. If Crowdin's locale code is different from our IETF language tag (such as Chinese Simplified), add a custom mapping in Project Settings -> Language mapping
2. Sync the new (empty) language to the repo
1. In Grafana's Github Actions, go to [Crowdin Download Action](https://github.com/grafana/grafana/actions/workflows/i18n-crowdin-download.yml)
2. Select 'Run workflow', from main
3. The workflow will create a PR with the new language files, which can be reviewed and merged
3. Update `public/app/core/internationalization/constants.ts`
1. Add a new constant for the new language
2. Add the new constant to the `LOCALES` array
3. Create a PR with the changes and merge when you are ready to release the new language (probably wait until we have translations for it)
4. In the Enterprise repo, update `src/public/locales/localeExtensions.ts`
1. Add a new locale in Crowdin.
1. Go to the Grafana OSS Crowdin project.
2. In the top right, select the "dot dot dot" menu.
3. Under **Target languages**, add the language.
4. If Crowdin's locale code is different from our IETF language tag (such as Chinese Simplified), add a custom mapping in **Project Settings** -> **Language mapping**.
2. Sync the new (empty) language to the repo.
1. In Grafana's Github Actions, go to [Crowdin Download Action](https://github.com/grafana/grafana/actions/workflows/i18n-crowdin-download.yml).
2. From main, select **Run workflow**.
3. The workflow creates a PR with the new language files, which can be reviewed and merged.
3. Update `public/app/core/internationalization/constants.ts`.
1. Add a new constant for the new language.
2. Add the new constant to the `LOCALES` array.
3. Create a PR with the changes and merge when you are ready to release the new language (as a general rule, wait until we have translations for it).
4. In the Grafana Enterprise repo, update `src/public/locales/localeExtensions.ts`.
## How translations work in Grafana
Grafana uses the [i18next](https://www.i18next.com/) framework for managing translating phrases in the Grafana frontend. It:
- Marks up phrases within our code for extraction
- Extracts phrases into the default messages catalogue for translating in external systems
- Manages the user's locale and putting the translated phrases in the UI
- Marks up phrases within our code for extraction.
- Extracts phrases into the default messages catalog for translating in external systems.
- Manages the user's locale and puts the translated phrases in the UI.
Grafana will load the message catalogue JSON before the initial render.
Grafana loads the message catalog JSON before the initial render.
### Phrase ID naming convention
We set explicit IDs for phrases to make it easier to identify phrases out of context, and to track where they're used. IDs follow a naming scheme that includes _where_ the phrase is used. The exception is the rare case of single reoccuring words like "Cancel", but default to using a feature/phrase specific phrase.
We set explicit IDs for phrases to make it easier to identify phrases out of context, and to track where they're used.
IDs follow a naming scheme that includes _where_ the phrase is used. The exception is the rare case of a single reoccurring word like "Cancel", but the default is to use a feature-specific phrase.
Message IDs are made of _up to_ three segments in the format `feature.area.phrase`. For example:
@ -107,11 +109,11 @@ For components used all over the site, use just two segments:
### I18next context
We rely on a global i18next singleton (that lives inside the i18next) for storing the i18next config/context.
We rely on a global i18next singleton (that lives inside the i18next) for storing the i18next configuration.
## Examples
See [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/) documentation for more details.
Refer to the [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/) documentation for more details.
### Basic usage
@ -123,7 +125,7 @@ import { Trans } from 'app/core/internationalization';
<Trans i18nKey="page.greeting">Hello user!</Trans>;
```
To interpolate variables, include it as an object child. It's weird syntax, but Trans will do it's magic to make it work:
To interpolate a variable, include it as an object child. It's a weird syntax, but `Trans` will do its magic to make it work:
```jsx
import { Trans } from 'app/core/internationalization';
@ -134,7 +136,7 @@ const userName = user.name;
<Trans i18nKey="page.greeting">Hello {{ userName }}!</Trans>;
```
Variables must be strings (or, must support calling `.toString()`, which we almost never want).
Variables must be strings (or, must support calling `.toString()`, which we almost never want). For example:
```jsx
import { Trans } from 'app/core/internationalization';
@ -152,7 +154,7 @@ const userName = user.name;
### React components and HTML tags
Both HTML tags and React components can be included in a phase. The Trans function will handle interpolating it's children properly
Both HTML tags and React components can be included in a phase. The `Trans` function handles interpolating for its children.
```js
import { Trans } from "app/core/internationalization"
@ -171,23 +173,23 @@ import { Trans } from "app/core/internationalization"
### Plurals
Plurals require special handling to make sure they can be translating according to the rules of each locale (which may be more complex that you think!). Use either the `<Trans />` component or the `t` function, with the `count` prop to provide a singular form.
Plurals require special handling to make sure they can be translated according to the rules of each locale (which may be more complex than you think). Use either the `<Trans />` component or the `t` function, with the `count` prop to provide a singular form. For example:
```js
import { Trans } from 'app/core/internationalization';
<Trans i18nKey="inbox.heading" count={messages.length}>
You got {{ count: messages.length }} message
You got {{ count: messages.length }} messages
</Trans>;
```
```js
import { t } from 'app/core/internationalization';
const translatedString = t('inbox.heading', 'You got {{count}} message', { count: messages.length });
const translatedString = t('inbox.heading', 'You got {{count}} messages', { count: messages.length });
```
Once extracted with `make i18n-extract` you will need to manually edit the [English grafana.json message catalogue](../public/locales/en-US/grafana.json) to correct the plural forms. See the [react-i18next docs](https://react.i18next.com/latest/trans-component#plural) for more details.
Once extracted with `make i18n-extract` you need to manually edit the [English `grafana.json` message catalog](../public/locales/en-US/grafana.json) to correct the plural forms. Refer to the [react-i18next docs](https://react.i18next.com/latest/trans-component#plural) for more details.
```json
{
@ -200,20 +202,19 @@ Once extracted with `make i18n-extract` you will need to manually edit the [Engl
## Feedback
**Please note:** This is only for proofreaders with permissions to Grafana OSS project on Crowdin.
**Note:** This is only for proofreaders with permissions to the Grafana OSS project on Crowdin.
To provide feedback on translations, sign into Crowdin and follow these steps:
1. Open the Grafana OSS project in Crowdin.
2. In the left-hand menu, click on the 'Dashboard' menu item.
3. A list of available languages appears under the 'Translations' section. Click on the one you want to comment on.
4. There is a table with the file structure in it:
1. On the left menu, click **Dashboard**. A list of available languages appears under the **Translations** section. Click the one you want to comment on.
1. There is a table with the file structure in it:
<br>
`grafana/main > public > locales > 'language denomination' > grafana.json`
<br>
Click on the `grafana.json` file.
5. In the left-hand section, click on the 'Search in file' input and search for the string that you want to comment on. You can search in English, as it is the default language, or in the language the string is translated to.
6. Once you have found the string, on the right hand side there is a 'Comments' section where you can send the feedback about the translation. Tag @Translated to be sure the team of linguists gets notified.
Click the `grafana.json` file.
1. In the left section, click the **Search in file** input. Search for the string that you want to comment on. You can search in English, as it's the default language, or in the language the string is translated into.
1. Once you have found the string, on the right hand side there is a **Comments** section where you can send your feedback about the translation. Tag `@Translated` to be sure the team of linguists gets notified.
## Documentation