Thank you for sending a pull request! Here are some tips:
Thank you for sending a pull request! Here are some tips:
1. If this is your first time, please read our contribution guide at https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md
1. If this is your first time, please read our contribution guide at https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md
2. Ensure you include and run the appropriate tests as part of your Pull Request.
2. Ensure you include and run the appropriate tests as part of your Pull Request.
@ -10,7 +10,7 @@ Thank you for sending a pull request! Here are some tips:
4. If the Pull Request is a work in progress, make use of GitHub's "Draft PR" feature and mark it as such.
4. If the Pull Request is a work in progress, make use of GitHub's "Draft PR" feature and mark it as such.
5. If you can not merge your Pull Request due to a merge conflict, Rebase it. This gets it in sync with the master branch.
5. If you can not merge your Pull Request due to a merge conflict, Rebase it. This gets it in sync with the main branch.
6. Name your PR as "<FeatureArea>: Describe your change", e.g. Alerting: Prevent race condition. If it's a fix or feature relevant for the changelog describe the user impact in the title. The PR title is used to auto-generate the changelog for issues marked with the "add to changelog" label.
6. Name your PR as "<FeatureArea>: Describe your change", e.g. Alerting: Prevent race condition. If it's a fix or feature relevant for the changelog describe the user impact in the title. The PR title is used to auto-generate the changelog for issues marked with the "add to changelog" label.
The bot is configured via [commands.json](https://github.com/grafana/grafana/blob/master/.github/commands.json) and some other GitHub workflows [workflows](https://github.com/grafana/grafana/tree/master/.github/workflows).
The bot is configured via [commands.json](https://github.com/grafana/grafana/blob/main/.github/commands.json) and some other GitHub workflows [workflows](https://github.com/grafana/grafana/tree/main/.github/workflows).
Comment commands:
Comment commands:
@ -17,7 +17,7 @@ Label commands:
## Metrics
## Metrics
Metrics are configured in [metrics-collector.json](https://github.com/grafana/grafana/blob/master/.github/metrics-collector.json) and are also defined in the
Metrics are configured in [metrics-collector.json](https://github.com/grafana/grafana/blob/main/.github/metrics-collector.json) and are also defined in the
"comment":"Please ask your question on [community.grafana.com/](https://community.grafana.com/). To avoid having your issue closed in the future, please read our [CONTRIBUTING](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md) guidelines.\n\nHappy graphing!"
"comment":"Please ask your question on [community.grafana.com/](https://community.grafana.com/). To avoid having your issue closed in the future, please read our [CONTRIBUTING](https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md) guidelines.\n\nHappy graphing!"
},
},
{
{
"type":"comment",
"type":"comment",
@ -20,7 +20,7 @@
"addLabel":"type/duplicate",
"addLabel":"type/duplicate",
"removeLabel":"bot/duplicate",
"removeLabel":"bot/duplicate",
"action":"close",
"action":"close",
"comment":"Thanks for creating this issue! It looks like this has already been reported by another user. We’ve closed this in favor of the existing one. Please consider adding any details you think is missing to that issue.\n\nTo avoid having your issue closed in the future, please read our [CONTRIBUTING](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md) guidelines.\n\nHappy graphing!"
"comment":"Thanks for creating this issue! It looks like this has already been reported by another user. We’ve closed this in favor of the existing one. Please consider adding any details you think is missing to that issue.\n\nTo avoid having your issue closed in the future, please read our [CONTRIBUTING](https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md) guidelines.\n\nHappy graphing!"
},
},
{
{
"type":"comment",
"type":"comment",
@ -41,7 +41,7 @@
"type":"label",
"type":"label",
"name":"bot/no new info",
"name":"bot/no new info",
"action":"close",
"action":"close",
"comment":"We've closed this issue since it needs more information and hasn't had any activity recently. We can re-open it after you you add more information. To avoid having your issue closed in the future, please read our [CONTRIBUTING](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md) guidelines.\n\nHappy graphing!"
"comment":"We've closed this issue since it needs more information and hasn't had any activity recently. We can re-open it after you you add more information. To avoid having your issue closed in the future, please read our [CONTRIBUTING](https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md) guidelines.\n\nHappy graphing!"
@ -301,12 +301,12 @@ Even if you don't have the time or knowledge to investigate an issue we highly r
## 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/master/.github/commands.json). Or in other [GitHub Actions](https://github.com/grafana/grafana/tree/master/.github/workflows)
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)
* Add /duplicate `#<issue number>` to have Grafana label & close issue with an appropriate message.
* Add /duplicate `#<issue number>` to have Grafana label & close issue with an appropriate message.
* Add `bot/question` and the bot will close it with an appropriate message.
* Add `bot/question` and the bot will close it with an appropriate message.
[Read more on bot actions](https://github.com/grafana/grafana/blob/master/.github/bot.md)
[Read more on bot actions](https://github.com/grafana/grafana/blob/main/.github/bot.md)
@ -17,7 +17,7 @@ for built-in plugins and everything internal. External plugins still use systemj
set of Grafana components they can import. Plugins can depend on libs like lodash & moment and internal components
set of Grafana components they can import. Plugins can depend on libs like lodash & moment and internal components
like before using the same import paths. However since everything in Grafana is no longer accessible, a few plugins could encounter issues when importing a Grafana dependency.
like before using the same import paths. However since everything in Grafana is no longer accessible, a few plugins could encounter issues when importing a Grafana dependency.
[List of exposed components plugins can import/require](https://github.com/grafana/grafana/blob/master/public/app/features/plugins/plugin_loader.ts#L48)
[List of exposed components plugins can import/require](https://github.com/grafana/grafana/blob/main/public/app/features/plugins/plugin_loader.ts#L48)
If you think we missed exposing a crucial lib or Grafana component let us know by opening an issue.
If you think we missed exposing a crucial lib or Grafana component let us know by opening an issue.
@ -12,7 +12,7 @@ Team members and their access to repositories is maintained through [GitHub team
## Proposing changes
## Proposing changes
Examples of proposed changes are overarching architecture, component design, and specific code or graphical elements. Proposed changes SHOULD cover the big picture and intention, but individual parts SHOULD be split into the smallest possible changes. Changes SHOULD be based on and target the master branch. Depending on size of the proposed change, each change SHOULD be discussed, in increasing order of change size and complexity:
Examples of proposed changes are overarching architecture, component design, and specific code or graphical elements. Proposed changes SHOULD cover the big picture and intention, but individual parts SHOULD be split into the smallest possible changes. Changes SHOULD be based on and target the main branch. Depending on size of the proposed change, each change SHOULD be discussed, in increasing order of change size and complexity:
- Directly in a RR (Pull Request) - this MAY be done, but SHOULD not be the common case.
- Directly in a RR (Pull Request) - this MAY be done, but SHOULD not be the common case.
- Issue
- Issue
- Developer mailing list
- Developer mailing list
@ -23,7 +23,7 @@ Significant changes MUST be discussed and agreed upon with the relevant subsyste
## Merging PRs (Pull Requests)
## Merging PRs (Pull Requests)
Depending on the size and complexity of a PR, different requirements MUST be applied. Any team member contributing substantially to a PR MUST NOT count against review requirements.
Depending on the size and complexity of a PR, different requirements MUST be applied. Any team member contributing substantially to a PR MUST NOT count against review requirements.
Commits MUST be merged into master using PRs. They MUST NOT be merged into master directly.
Commits MUST be merged into main using PRs. They MUST NOT be merged into main directly.
- Every merge MUST be approved by at least one team member.
- Every merge MUST be approved by at least one team member.
- Non-trivial changes MUST be approved by at least
- Non-trivial changes MUST be approved by at least
- two team members, or
- two team members, or
@ -40,7 +40,7 @@ Once a PR is approved as per above, any team member MAY merge the PR.
## Backporting a PR
## Backporting a PR
PRs intended for inclusion in the next PATCH release they must be backported to the release branch. The bot can do this automatically. [Read more on backport PRs](https://github.com/grafana/grafana/blob/master/.github/bot.md). Both the source PR and the backport PR should be assigned to the patch release milestone, unless you are backporting to many releases then it can differ.
PRs intended for inclusion in the next PATCH release they must be backported to the release branch. The bot can do this automatically. [Read more on backport PRs](https://github.com/grafana/grafana/blob/main/.github/bot.md). Both the source PR and the backport PR should be assigned to the patch release milestone, unless you are backporting to many releases then it can differ.
Backport PRs are also needed during the beta period to get fixes into the stable release.
Backport PRs are also needed during the beta period to get fixes into the stable release.
@ -51,7 +51,7 @@ Backport PRs are also needed during the beta period to get fixes into the stable
Grafana uses trunk-based development.
Grafana uses trunk-based development.
In particular, we found that the following principles match how we work:
In particular, we found that the following principles match how we work:
- Master and release branches MUST always build without failure.
- Main and release branches MUST always build without failure.
- Branches SHOULD be merged often. Larger changes SHOULD be activated with feature flags until they are ready. Long-lived development branches SHOULD be avoided.
- Branches SHOULD be merged often. Larger changes SHOULD be activated with feature flags until they are ready. Long-lived development branches SHOULD be avoided.
- Changes MAY be enabled by default once they are in a complete state
- Changes MAY be enabled by default once they are in a complete state
- Changes which span multiple PRs MUST be described in an overarching issue or Google Doc.
- Changes which span multiple PRs MUST be described in an overarching issue or Google Doc.
@ -61,8 +61,8 @@ In particular, we found that the following principles match how we work:
Releases MUST follow [Semantic Versioning](https://semver.org/) in naming and SHOULD follow Semantic Versioning as closely as reasonably possible for non-library software.
Releases MUST follow [Semantic Versioning](https://semver.org/) in naming and SHOULD follow Semantic Versioning as closely as reasonably possible for non-library software.
Release branches MUST be split from the following branches.
Release branches MUST be split from the following branches.
- MAJOR release branches MUST be based on master.
- MAJOR release branches MUST be based on main.
- MINOR release branches MUST be based on master.
- MINOR release branches MUST be based on main.
- PATCH release branches MUST be split from the relevant MINOR release branch’s most current PATCH
- PATCH release branches MUST be split from the relevant MINOR release branch’s most current PATCH
Security releases follow the same process but MUST be prepared in secret. Security releases MUST NOT include changes which are not related to the security fix. Normal release processes MUST accommodate the security release process. SECURITY.md MUST be followed.
Security releases follow the same process but MUST be prepared in secret. Security releases MUST NOT include changes which are not related to the security fix. Normal release processes MUST accommodate the security release process. SECURITY.md MUST be followed.
@ -12,7 +12,7 @@ If we wait for canceled requests to complete, it might create unnecessary load o
Grafana uses a concept called _request cancelation_ to cancel any ongoing request that Grafana doesn't need.
Grafana uses a concept called _request cancelation_ to cancel any ongoing request that Grafana doesn't need.
#### Before Grafana 7.2
#### Before Grafana 7.2
Before Grafana can cancel any data request, it has to identify that request. Grafana identifies a request using the property `requestId` [passed as options](https://github.com/grafana/grafana/blob/master/docs/sources/packages_api/runtime/backendsrvrequest.md) when you use [BackendSrv](https://grafana.com/docs/grafana/latest/packages_api/runtime/backendsrv).
Before Grafana can cancel any data request, it has to identify that request. Grafana identifies a request using the property `requestId` [passed as options](https://github.com/grafana/grafana/blob/main/docs/sources/packages_api/runtime/backendsrvrequest.md) when you use [BackendSrv](https://grafana.com/docs/grafana/latest/packages_api/runtime/backendsrv).
The cancellation logic is as follows:
The cancellation logic is as follows:
- When an ongoing request discovers that an additional request with the same `requestId` has started, then Grafana will cancel the ongoing request.
- When an ongoing request discovers that an additional request with the same `requestId` has started, then Grafana will cancel the ongoing request.
@ -114,7 +114,7 @@ If that is the case, then use the following format for headings:
- Assume all graphics will be exclusively viewed on the web.
- Assume all graphics will be exclusively viewed on the web.
- Maximum image size is 3840px X 2160px.
- Maximum image size is 3840px X 2160px.
- Screenshots should be readable, but not too large.
- Screenshots should be readable, but not too large.
- _Do not_ use image shortcodes. Follow the guidance in the [Grafana markdown guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/documentation-markdown-guide.md#images).
- _Do not_ use image shortcodes. Follow the guidance in the [Grafana markdown guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/documentation-markdown-guide.md#images).
- Markdown image links are preferred. Only use the HTML image links if you need to style the image in ways unsupported in Markdown.
- Markdown image links are preferred. Only use the HTML image links if you need to style the image in ways unsupported in Markdown.
- When you name a file, follow the [file naming conventions](#file-naming-conventions). Example: image-name-7-3.png
- When you name a file, follow the [file naming conventions](#file-naming-conventions). Example: image-name-7-3.png
@ -147,7 +147,7 @@ The [controls addon](https://storybook.js.org/docs/react/essentials/controls) pr
#### Migrating a story from Knobs to Controls
#### Migrating a story from Knobs to Controls
As a test, we migrated the [button story](https://github.com/grafana/grafana/blob/master/packages/grafana-ui/src/components/Button/Button.story.tsx). Here's the guide on how to migrate a story to controls.
As a test, we migrated the [button story](https://github.com/grafana/grafana/blob/main/packages/grafana-ui/src/components/Button/Button.story.tsx). Here's the guide on how to migrate a story to controls.
1. Remove the `@storybook/addon-knobs` dependency.
1. Remove the `@storybook/addon-knobs` dependency.
@ -44,6 +44,6 @@ Images are currently hosted in the grafana/website repo.
## Deploy changes to grafana.com
## Deploy changes to grafana.com
When a PR is merged to master with changes in the `docs/sources` directory, those changes are automatically synced to the grafana/website repo and published to the staging site.
When a PR is merged to main with changes in the `docs/sources` directory, those changes are automatically synced to the grafana/website repo and published to the staging site.
Generally, someone from marketing will publish to production each day: so as long as the sync is successful your docs edits will be published. Alternatively, you can refer to [publishing to production](https://github.com/grafana/website#publishing-to-production-grafanacom) if you'd like to do it yourself.
Generally, someone from marketing will publish to production each day: so as long as the sync is successful your docs edits will be published. Alternatively, you can refer to [publishing to production](https://github.com/grafana/website#publishing-to-production-grafanacom) if you'd like to do it yourself.
Not all metrics returned by the Azure Monitor Metrics API have values. To make it easier for you when building a query, the Grafana data source has a list of supported metrics and ignores metrics which will never have values. This list is updated regularly as new services and metrics are added to the Azure cloud. For more information about the list of metrics, refer to [current supported namespaces](https://github.com/grafana/grafana/blob/master/public/app/plugins/datasource/grafana-azure-monitor-datasource/azure_monitor/supported_namespaces.ts).
Not all metrics returned by the Azure Monitor Metrics API have values. To make it easier for you when building a query, the Grafana data source has a list of supported metrics and ignores metrics which will never have values. This list is updated regularly as new services and metrics are added to the Azure cloud. For more information about the list of metrics, refer to [current supported namespaces](https://github.com/grafana/grafana/blob/main/public/app/plugins/datasource/grafana-azure-monitor-datasource/azure_monitor/supported_namespaces.ts).
@ -11,32 +11,32 @@ This page lists resources for developers who want to contribute to the Grafana s
These resources are useful for all developers.
These resources are useful for all developers.
- [Contributing to Grafana](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md): Start here to learn how you can contribute your skills to make Grafana even better.
- [Contributing to Grafana](https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md): Start here to learn how you can contribute your skills to make Grafana even better.
- [Developer guide](https://github.com/grafana/grafana/blob/master/contribute/developer-guide.md): A guide to help you get started developing Grafana software, includes instructions for how to configure Grafana for development.
- [Developer guide](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md): A guide to help you get started developing Grafana software, includes instructions for how to configure Grafana for development.
- [Contributing to documentation](https://github.com/grafana/grafana/blob/master/contribute/documentation.md): A guide to help you contribute to Grafana documentation, includes links to beginner-friendly issues.
- [Contributing to documentation](https://github.com/grafana/grafana/blob/main/contribute/documentation.md): A guide to help you contribute to Grafana documentation, includes links to beginner-friendly issues.
- [Architecture guides](https://github.com/grafana/grafana/tree/master/contribute/architecture): These guides explain Grafana’s background architecture.
- [Architecture guides](https://github.com/grafana/grafana/tree/main/contribute/architecture): These guides explain Grafana’s background architecture.
- [Create a pull request](https://github.com/grafana/grafana/blob/master/contribute/create-pull-request.md): A guide for new contributors about how to create your first Grafana pull request.
- [Create a pull request](https://github.com/grafana/grafana/blob/main/contribute/create-pull-request.md): A guide for new contributors about how to create your first Grafana pull request.
- [REST APIs](https://grafana.com/docs/grafana/next/http_api/) allow you to interact programmatically with the Grafana backend.
- [REST APIs](https://grafana.com/docs/grafana/next/http_api/) allow you to interact programmatically with the Grafana backend.
## Best practices and style
## Best practices and style
Our [style guides](https://github.com/grafana/grafana/tree/master/contribute/style-guides) outline Grafana style for frontend, backend, documentation, and more, including best practices. Please read through them before you start editing or coding!
Our [style guides](https://github.com/grafana/grafana/tree/main/contribute/style-guides) outline Grafana style for frontend, backend, documentation, and more, including best practices. Please read through them before you start editing or coding!
- [Backend style guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/backend.md) explains how we want to write Go code in the future.
- [Backend style guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/backend.md) explains how we want to write Go code in the future.
- [Documentation style guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/documentation-style-guide.md) applies to all documentation created for Grafana products.
- [Documentation style guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/documentation-style-guide.md) applies to all documentation created for Grafana products.
- [End to end test framework](https://github.com/grafana/grafana/blob/master/contribute/style-guides/e2e.md) provides guidance for Grafana e2e tests.
- [End to end test framework](https://github.com/grafana/grafana/blob/main/contribute/style-guides/e2e.md) provides guidance for Grafana e2e tests.
- [Frontend style guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/frontend.md) provides rules and guidance on developing in React for Grafana.
- [Frontend style guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/frontend.md) provides rules and guidance on developing in React for Grafana.
- [Redux framework](https://github.com/grafana/grafana/blob/master/contribute/style-guides/redux.md) explains how Grafana handles Redux boilerplate code.
- [Redux framework](https://github.com/grafana/grafana/blob/main/contribute/style-guides/redux.md) explains how Grafana handles Redux boilerplate code.
- [Styling Grafana](https://github.com/grafana/grafana/blob/master/contribute/style-guides/styling.md) expands on styling React components with Emotion.
- [Styling Grafana](https://github.com/grafana/grafana/blob/main/contribute/style-guides/styling.md) expands on styling React components with Emotion.
- [Theming Grafana](https://github.com/grafana/grafana/blob/master/contribute/style-guides/themes.md) explains how to use themes and ThemeContext in Grafana code.
- [Theming Grafana](https://github.com/grafana/grafana/blob/main/contribute/style-guides/themes.md) explains how to use themes and ThemeContext in Grafana code.
@ -173,7 +173,7 @@ The data frame structure is inspired by, and uses the [Apache Arrow Project](htt
### Javascript
### Javascript
The Javascript implementation of data frames is in the [`/src/dataframe` folder](https://github.com/grafana/grafana/tree/master/packages/grafana-data/src/dataframe) and [`/src/types/dataframe.ts`](https://github.com/grafana/grafana/blob/master/packages/grafana-data/src/types/dataFrame.ts) of the [`@grafana/data` package](https://github.com/grafana/grafana/tree/master/packages/grafana-data).
The Javascript implementation of data frames is in the [`/src/dataframe` folder](https://github.com/grafana/grafana/tree/main/packages/grafana-data/src/dataframe) and [`/src/types/dataframe.ts`](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/types/dataFrame.ts) of the [`@grafana/data` package](https://github.com/grafana/grafana/tree/main/packages/grafana-data).
> **Note:** Grafana displays the exception message in the UI as written, so we recommend using grammatically correct sentences. For more information, refer to the [Documentation style guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/documentation-style-guide.md).
> **Note:** Grafana displays the exception message in the UI as written, so we recommend using grammatically correct sentences. For more information, refer to the [Documentation style guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/documentation-style-guide.md).
Here are some examples of situations where you might want to display an error to the user.
Here are some examples of situations where you might want to display an error to the user.
@ -13,7 +13,7 @@ Grafana already has a strong community of contributors and plugin developers. By
## Short version
## Short version
1. [Set up Grafana](https://github.com/grafana/grafana/blob/master/contribute/developer-guide.md)
1. [Set up Grafana](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md)
1. Clone an example plugin into `/var/lib/grafana/plugins` or `data/plugins` (relative to grafana git repo if you're running development version from source dir)
1. Clone an example plugin into `/var/lib/grafana/plugins` or `data/plugins` (relative to grafana git repo if you're running development version from source dir)
1. Use one of our example plugins as a starting point
1. Use one of our example plugins as a starting point
@ -39,7 +39,7 @@ You can use any build system that supports systemjs. All the built content shoul
## Keep your plugin up to date
## Keep your plugin up to date
New versions of Grafana can sometimes cause plugins to break. Check out our [PLUGIN_DEV.md](https://github.com/grafana/grafana/blob/master/PLUGIN_DEV.md) doc for changes in
New versions of Grafana can sometimes cause plugins to break. Check out our [PLUGIN_DEV.md](https://github.com/grafana/grafana/blob/main/PLUGIN_DEV.md) doc for changes in
Grafana that can impact your plugin.
Grafana that can impact your plugin.
## Metadata
## Metadata
@ -55,7 +55,7 @@ and [apps]({{< relref "apps.md" >}}) plugins in the documentation.
The Grafana SDK is quite small so far and can be found here:
The Grafana SDK is quite small so far and can be found here:
- [SDK file in Grafana](https://github.com/grafana/grafana/blob/master/public/app/plugins/sdk.ts)
- [SDK file in Grafana](https://github.com/grafana/grafana/blob/main/public/app/plugins/sdk.ts)
The SDK contains three different plugin classes: PanelCtrl, MetricsPanelCtrl and QueryCtrl. For plugins of the panel type, the module.js file should export one of these. There are some extra classes for [data sources]({{< relref "data-sources.md" >}}).
The SDK contains three different plugin classes: PanelCtrl, MetricsPanelCtrl and QueryCtrl. For plugins of the panel type, the module.js file should export one of these. There are some extra classes for [data sources]({{< relref "data-sources.md" >}}).
@ -85,7 +85,7 @@ export { WorldmapCtrl as PanelCtrl };
There are three ways that you can start developing a Grafana plugin.
There are three ways that you can start developing a Grafana plugin.
1. Set up a Grafana development environment. [(described here)](https://github.com/grafana/grafana/blob/master/contribute/developer-guide.md) and place your plugin in the `data/plugins` folder.
1. Set up a Grafana development environment. [(described here)](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md) and place your plugin in the `data/plugins` folder.
1. Install Grafana and place your plugin in the plugins directory which is set in your [config file](/administration/configuration). By default this is `/var/lib/grafana/plugins` on Linux systems.
1. Install Grafana and place your plugin in the plugins directory which is set in your [config file](/administration/configuration). By default this is `/var/lib/grafana/plugins` on Linux systems.
1. Place your plugin directory anywhere you like and specify it grafana.ini.
1. Place your plugin directory anywhere you like and specify it grafana.ini.
@ -114,7 +114,7 @@ We have three different examples that you can fork/download to get started devel
- [simple-json-datasource](https://github.com/grafana/simple-json-datasource) (small data source plugin for querying json data from backends)
- [simple-json-datasource](https://github.com/grafana/simple-json-datasource) (small data source plugin for querying json data from backends)
For editor tabs html, it is best to use Grafana css styles rather than custom styles. This is to preserve the look and feel of other tabs in Grafana.
For editor tabs html, it is best to use Grafana css styles rather than custom styles. This is to preserve the look and feel of other tabs in Grafana.
Most editor tabs should use the [gf-form css class](https://github.com/grafana/grafana/blob/master/public/sass/components/_gf-form.scss)from Grafana. The example below has one row with a couple of columns and each column is wrapped in a divlike this:
Most editor tabs should use the [gf-form css class](https://github.com/grafana/grafana/blob/main/public/sass/components/_gf-form.scss)from Grafana. The example below has one row with a couple of columns and each column is wrapped in a divlike this:
@ -39,7 +39,7 @@ To add MS SQL Server data source:
`User` | Database user's login/username.
`User` | Database user's login/username.
`Password` | Database user's password.
`Password` | Database user's password.
For installations from the [grafana/grafana](https://github.com/grafana/grafana/tree/master) repository, `gdev-mssql` data source is available. Once you add this data source, you can use the `Datasource tests - MSSQL` dashboard with three panels showing metrics generated from a test database.
For installations from the [grafana/grafana](https://github.com/grafana/grafana/tree/main) repository, `gdev-mssql` data source is available. Once you add this data source, you can use the `Datasource tests - MSSQL` dashboard with three panels showing metrics generated from a test database.
@ -28,7 +28,7 @@ This image is based on [Ubuntu](https://ubuntu.com/), available in [the Ubuntu o
> **Note:** The `grafana/grafana:<version>-ubuntu` image is available for Grafana version 6.5.0 and later.
> **Note:** The `grafana/grafana:<version>-ubuntu` image is available for Grafana version 6.5.0 and later.
## Run Grafana
## Run Grafana
You can run the latest Grafana version, run a specific version, or run an unstable version based on the master branch of the [grafana/grafana GitHub repository](https://github.com/grafana/grafana).
You can run the latest Grafana version, run a specific version, or run an unstable version based on the main branch of the [grafana/grafana GitHub repository](https://github.com/grafana/grafana).
docker run -d -p 3000:3000 --name grafana grafana/grafana:6.5.0
docker run -d -p 3000:3000 --name grafana grafana/grafana:6.5.0
```
```
### Run the Grafana master branch
### Run the Grafana main branch
For every successful build of the master branch, we update the `grafana/grafana:master` and `grafana/grafana:master-ubuntu` tags. Additionally, two new tags are created, `grafana/grafana-dev:<version>-<build ID>pre` and `grafana/grafana-dev:<version>-<build ID>pre-ubuntu`, where *version* is the next version of Grafana and *build ID* is the ID of the corresponding CI build. Use these to get access to the latest master builds of Grafana.
For every successful build of the main branch, we update the `grafana/grafana:main` and `grafana/grafana:main-ubuntu` tags. Additionally, two new tags are created, `grafana/grafana-dev:<version>-<build ID>pre` and `grafana/grafana-dev:<version>-<build ID>pre-ubuntu`, where *version* is the next version of Grafana and *build ID* is the ID of the corresponding CI build. Use these to get access to the latest main builds of Grafana.
When running Grafana master in production, we *strongly* recommend that you use the `grafana/grafana-dev:<version>-<build ID>pre` tag. This tag guarantees that you use a specific version of Grafana instead of whatever was the most recent commit at the time.
When running Grafana main in production, we *strongly* recommend that you use the `grafana/grafana-dev:<version>-<build ID>pre` tag. This tag guarantees that you use a specific version of Grafana instead of whatever was the most recent commit at the time.
For a list of available tags, check out [grafana/grafana](https://hub.docker.com/r/grafana/grafana/tags/) and [grafana/grafana-dev](https://hub.docker.com/r/grafana/grafana-dev/tags/).
For a list of available tags, check out [grafana/grafana](https://hub.docker.com/r/grafana/grafana/tags/) and [grafana/grafana-dev](https://hub.docker.com/r/grafana/grafana-dev/tags/).
@ -11,7 +11,7 @@ This page lists the minimum hardware and software requirements to install Grafan
To run Grafana, you must have a supported operating system, hardware that meets or exceeds minimum requirements, a supported database, and a supported browser.
To run Grafana, you must have a supported operating system, hardware that meets or exceeds minimum requirements, a supported database, and a supported browser.
Grafana uses other open source software. Refer to [package.json](https://github.com/grafana/grafana/blob/master/package.json) for a complete list.
Grafana uses other open source software. Refer to [package.json](https://github.com/grafana/grafana/blob/main/package.json) for a complete list.
We recommend that you upgrade Grafana often to stay up to date with the latest fixes and enhancements.
We recommend that you upgrade Grafana often to stay up to date with the latest fixes and enhancements.
In order to make this a reality, Grafana upgrades are backward compatible and the upgrade process is simple and quick.
In order to make this a reality, Grafana upgrades are backward compatible and the upgrade process is simple and quick.
Upgrading is generally safe (between many minor and one major version) and dashboards and graphs will look the same. There may be minor breaking changes in some edge cases, which are outlined in the [Release Notes](https://community.grafana.com/c/releases) and [Changelog](https://github.com/grafana/grafana/blob/master/CHANGELOG.md)
Upgrading is generally safe (between many minor and one major version) and dashboards and graphs will look the same. There may be minor breaking changes in some edge cases, which are outlined in the [Release Notes](https://community.grafana.com/c/releases) and [Changelog](https://github.com/grafana/grafana/blob/main/CHANGELOG.md)
- Grafana - master branch version (based on package.json, i.e. 6.4.0-pre) -> @grafana/* packages @ 6.4.0-pre-<COMMIT-SHA> (see details below about packages publishing channels)
- Grafana - main branch version (based on package.json, i.e. 6.4.0-pre) -> @grafana/* packages @ 6.4.0-pre-<COMMIT-SHA> (see details below about packages publishing channels)
> Please note that @grafana/toolkit, @grafana/ui, @grafana/data, and @grafana/runtime packages are considered ALPHA even though they are not released as alpha versions.
> Please note that @grafana/toolkit, @grafana/ui, @grafana/data, and @grafana/runtime packages are considered ALPHA even though they are not released as alpha versions.
@ -21,7 +21,7 @@ Stable releases are published under the `latest` tag on npm. If there was alpha/
Alpha and beta releases are published under the `next` tag on npm.
Alpha and beta releases are published under the `next` tag on npm.
### Automatic prereleases
### Automatic prereleases
Every commit to master that has changes within the `packages` directory is a subject of npm packages release. *ALL* packages must be released under version from lerna.json file with commit SHA added to it:
Every commit to main that has changes within the `packages` directory is a subject of npm packages release. *ALL* packages must be released under version from lerna.json file with commit SHA added to it:
```
```
<lerna.jsonversion>-<COMMIT_SHA>
<lerna.jsonversion>-<COMMIT_SHA>
@ -81,7 +81,7 @@ A known issue with @grafana/* packages is that a lot of times we discover proble
We can easily avoid that by setting up a local packages registry and test the packages before actually publishing to npm.
We can easily avoid that by setting up a local packages registry and test the packages before actually publishing to npm.
In this guide you will set up [Verdaccio](https://verdaccio.org/) registry locally to fake npm registry. This will enable testing @grafana/* packages without the need for pushing to master.
In this guide you will set up [Verdaccio](https://verdaccio.org/) registry locally to fake npm registry. This will enable testing @grafana/* packages without the need for pushing to main.
This package contains an API wrapper built on top of [Cypress](https://www.cypress.io) that simplifies creating end-to-end tests for Grafana. More information can be found [here](https://github.com/grafana/grafana/blob/master/contribute/style-guides/e2e.md).
This package contains an API wrapper built on top of [Cypress](https://www.cypress.io) that simplifies creating end-to-end tests for Grafana. More information can be found [here](https://github.com/grafana/grafana/blob/main/contribute/style-guides/e2e.md).
@ -124,7 +124,7 @@ To generate a signature, you will need to sign up for a free account on https://
### Which version of grafana-toolkit should I use?
### Which version of grafana-toolkit should I use?
See [Grafana packages versioning guide](https://github.com/grafana/grafana/blob/master/packages/README.md#versioning).
See [Grafana packages versioning guide](https://github.com/grafana/grafana/blob/main/packages/README.md#versioning).
### What tools does grafana-toolkit use?
### What tools does grafana-toolkit use?
@ -240,7 +240,7 @@ const MyComponent = () => {
};
};
```
```
To learn more about using Grafana theme please refer to [Theme usage guide](https://github.com/grafana/grafana/blob/master/style_guides/themes.md#react)
To learn more about using Grafana theme please refer to [Theme usage guide](https://github.com/grafana/grafana/blob/main/style_guides/themes.md#react)
> We do not support Emotion's `css` prop. Use className instead!
> We do not support Emotion's `css` prop. Use className instead!
@ -261,7 +261,7 @@ Yes! However, it's important that your `tsconfig.json` file contains the followi
### Can I adjust ESLint configuration to suit my needs?
### Can I adjust ESLint configuration to suit my needs?
grafana-toolkit comes with [default config for ESLint](https://github.com/grafana/grafana/blob/master/packages/grafana-toolkit/src/config/eslint.plugin.json). For now, there is no way to customise ESLint config.
grafana-toolkit comes with [default config for ESLint](https://github.com/grafana/grafana/blob/main/packages/grafana-toolkit/src/config/eslint.plugin.json). For now, there is no way to customise ESLint config.
### How is Prettier integrated into grafana-toolkit workflow?
### How is Prettier integrated into grafana-toolkit workflow?
@ -8,7 +8,7 @@ Our goal is to deliver Grafana's common UI elements for plugins developers and c
Browse the [Storybook catalog of the components](http://developers.grafana.com/).
Browse the [Storybook catalog of the components](http://developers.grafana.com/).
See [package source](https://github.com/grafana/grafana/tree/master/packages/grafana-ui) for more details.
See [package source](https://github.com/grafana/grafana/tree/main/packages/grafana-ui) for more details.
## Installation
## Installation
@ -22,4 +22,4 @@ For development purposes we suggest using `yarn link` that will create symlink t
### Storybook 6.x migration
### Storybook 6.x migration
We've upgraded Storybook to version 6 and with that we will convert to using [controls](https://storybook.js.org/docs/react/essentials/controls) instead of knobs for manipulating components. Controls will not require as much coding as knobs do. Please refer to the [storybook style-guide](https://github.com/grafana/grafana/blob/master/contribute/style-guides/storybook.md#contrls) for further information.
We've upgraded Storybook to version 6 and with that we will convert to using [controls](https://storybook.js.org/docs/react/essentials/controls) instead of knobs for manipulating components. Controls will not require as much coding as knobs do. Please refer to the [storybook style-guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/storybook.md#contrls) for further information.
@ -10,7 +10,7 @@ With the design system @grafana/ui, we want to democratize development. This lib
## Our vision
## Our vision
Grafana Labs started @grafana/ui to make contributing to Grafana as easy as possible for Grafanistas and community members of all fields. We want to create a component library that results in:
Grafana Labs started @grafana/ui to make contributing to Grafana as easy as possible for Grafanistas and community members of all fields. We want to create a component library that results in:
- Understanding of how each component works and how you can use it to create a great user experience.
- Understanding of how each component works and how you can use it to create a great user experience.
- Short development times and consistent code quality.
- Short development times and consistent code quality.
- A beautiful, visually consistent Grafana experience.
- A beautiful, visually consistent Grafana experience.
- Transparency about how we work and what we do.
- Transparency about how we work and what we do.
@ -19,7 +19,7 @@ Grafana Labs started @grafana/ui to make contributing to Grafana as easy as poss
Grafana Labs has a task force that helps create and maintain components. We make sure that components are documented and easy to use. The current status of the @grafana/ui development is available on [GitHub](https://github.com/grafana/grafana/projects/26). Feel free to contribute!
Grafana Labs has a task force that helps create and maintain components. We make sure that components are documented and easy to use. The current status of the @grafana/ui development is available on [GitHub](https://github.com/grafana/grafana/projects/26). Feel free to contribute!
### How to get involved
### How to get involved
When we notice that we need to change something, we determine together what the change should be, then we put the change in place and communicate it publicly. Developers and designers create and improve @grafana/ui together. Throughout the process, we strive to involve you and meet your needs. We are looking forward to discussing your design and improvement ideas on [GitHub](https://github.com/grafana/grafana/projects/26).
When we notice that we need to change something, we determine together what the change should be, then we put the change in place and communicate it publicly. Developers and designers create and improve @grafana/ui together. Throughout the process, we strive to involve you and meet your needs. We are looking forward to discussing your design and improvement ideas on [GitHub](https://github.com/grafana/grafana/projects/26).
## Get started
## Get started
@ -31,7 +31,7 @@ When we notice that we need to change something, we determine together what the
- **Use them**
- **Use them**
Once you've found the right component for your use case, click the **Story** tab to see the code implementation, or look at examples under **Docs**.
Once you've found the right component for your use case, click the **Story** tab to see the code implementation, or look at examples under **Docs**.
For more details, refer to the [package source](https://github.com/grafana/grafana/tree/master/packages/grafana-ui).
For more details, refer to the [package source](https://github.com/grafana/grafana/tree/main/packages/grafana-ui).
@ -32,17 +32,17 @@ For more information on developing for the backend:
## Dependency management
## Dependency management
Refer to [UPGRADING_DEPENDENCIES.md](https://github.com/grafana/grafana/blob/master/UPGRADING_DEPENDENCIES.md).
Refer to [UPGRADING_DEPENDENCIES.md](https://github.com/grafana/grafana/blob/main/UPGRADING_DEPENDENCIES.md).
## Ongoing refactoring
## Ongoing refactoring
These issues are not something we want to address all at once but something we will improve incrementally. Since Grafana is released at a regular schedule the preferred approach is to do this in batches. Not only is it easier to review, but it also reduces the risk of conflicts when cherry-picking fixes from master to release branches. Please try to submit changes that span multiple locations at the end of the release cycle. We prefer to wait until the end because we make fewer patch releases at the end of the release cycle, so there are fewer opportunities for complications.
These issues are not something we want to address all at once but something we will improve incrementally. Since Grafana is released at a regular schedule the preferred approach is to do this in batches. Not only is it easier to review, but it also reduces the risk of conflicts when cherry-picking fixes from main to release branches. Please try to submit changes that span multiple locations at the end of the release cycle. We prefer to wait until the end because we make fewer patch releases at the end of the release cycle, so there are fewer opportunities for complications.
### Global state
### Global state
Global state makes testing and debugging software harder and it's something we want to avoid when possible. Unfortunately, there is quite a lot of global state in Grafana.
Global state makes testing and debugging software harder and it's something we want to avoid when possible. Unfortunately, there is quite a lot of global state in Grafana.
We want to migrate away from this by using the `inject` package to wire up all dependencies either in `pkg/cmd/grafana-server/main.go` or self-registering using `registry.RegisterService` ex https://github.com/grafana/grafana/blob/master/pkg/services/cleanup/cleanup.go#L25.
We want to migrate away from this by using the `inject` package to wire up all dependencies either in `pkg/cmd/grafana-server/main.go` or self-registering using `registry.RegisterService` ex https://github.com/grafana/grafana/blob/main/pkg/services/cleanup/cleanup.go#L25.
### Limit the use of the init() function
### Limit the use of the init() function
@ -79,8 +79,8 @@ Use of the `simplejson` package (`pkg/components/simplejson`) in place of types
All new features that require state should be possible to configure using config files. For example:
All new features that require state should be possible to configure using config files. For example:
echo"Please go to: https://github.com/grafana/grafana/blob/master/contribute/style-guides/code-comments.md for more information on how to add code comments."
echo"Please go to: https://github.com/grafana/grafana/blob/main/contribute/style-guides/code-comments.md for more information on how to add code comments."