diff --git a/CHANGELOG.md b/CHANGELOG.md index 04281710f89..38f057bdd66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,26 +64,22 @@ ### Breaking changes - The `monaco-editor` dependency in `grafana-ui` has been updated to a newer version (`0.27.0`), which is not completely backward compatible with the old version (`0.21.2`). The backward incompatible changes are fairly small, but they do exist, so if your code accesses the raw monaco-objects through the `grafana-ui` package, please check the [monaco-editor changelog](https://github.com/microsoft/monaco-editor/blob/main/CHANGELOG.md) and apply any necessary changes. Issue [#39027](https://github.com/grafana/grafana/issues/39027) - -The mandatory `css` prop in `grafana/ui` components has been removed. +The mandatory `css` prop in `grafana/ui` components has been removed. Previous versions of `grafana/ui` components were typed incorrectly due to a dependency mismatch between emotion 10 and 11 causing a `css` prop to be added to components that extended react types. - Issue [#38078](https://github.com/grafana/grafana/issues/38078) +Issue [#38078](https://github.com/grafana/grafana/issues/38078) +### Unified Alerting (Grafana 8 Alerting) data loss -### Unified Alerting (Grafana 8 Alerting) data loss +Grafana v8.2 fixed an issue with org isolation for notification configuration but to fix this Grafana will now re-run the migration from old alerting and this will cause complete removal of all new alert rules and notification configurations. This data loss is not something we find acceptable and are working on ways to mitigate it. So in the meantime, if you are an early adopter of unified alerting please wait with trying v8.2 beta. +Issue [#37414](https://github.com/grafana/grafana/issues/37414) -Grafana v8.2 fixed an issue with org isolation for notification configuration but to fix this Grafana will now re-run the migration from old alerting and this will cause complete removal of all new alert rules and notification configurations. This data loss is not something we find acceptable and are working on ways to mitigate it. So in the meantime, if you are an early adopter of unified alerting please wait with trying v8.2 beta. - Issue [#37414](https://github.com/grafana/grafana/issues/37414) - -Panel queries and/or annotation queries that used more than one statistic will be converted into one query/annotation per statistic. In case an alerting rule was based on a query row that had more than one statistic, it would now be based only on the first statistic for that query row. New alerting rules will not be created for migrated queries. Please note that in most cases it would not make sense to have an alerting rule that is based on multiple statistics anyway. Issue [#36925](https://github.com/grafana/grafana/issues/36925) +Panel queries and/or annotation queries that used more than one statistic will be converted into one query/annotation per statistic. In case an alerting rule was based on a query row that had more than one statistic, it would now be based only on the first statistic for that query row. New alerting rules will not be created for migrated queries. Please note that in most cases it would not make sense to have an alerting rule that is based on multiple statistics anyway. Issue [#36925](https://github.com/grafana/grafana/issues/36925) ### Deprecations - `getHighlighterExpressions` in datasource APIs ( used to highlight logs while editing queries) has been deprecated and will be removed in a future release. # Deprecation notice @@ -202,7 +198,7 @@ Panel queries and/or annotation queries that used more than one statistic will b - **Alerting:** Deduplicate receivers during migration. [#36812](https://github.com/grafana/grafana/pull/36812), [@codesome](https://github.com/codesome) - **ColorPicker:** Display colors as RGBA. [#37231](https://github.com/grafana/grafana/pull/37231), [@nikki-kiga](https://github.com/nikki-kiga) - **Encryption:** Add support for multiple encryption algorithms (aes-gcm). (Enterprise) -- **Select:** Make portalling the menu opt-in, but opt-in *everywhere*. [#37501](https://github.com/grafana/grafana/pull/37501), [@ashharrison90](https://github.com/ashharrison90) +- **Select:** Make portalling the menu opt-in, but opt-in _everywhere_. [#37501](https://github.com/grafana/grafana/pull/37501), [@ashharrison90](https://github.com/ashharrison90) - **TeamSync:** Batch team synchronization. (Enterprise) - **TimeRangePicker:** Improve accessibility. [#36912](https://github.com/grafana/grafana/pull/36912), [@tskarhed](https://github.com/tskarhed) @@ -291,9 +287,9 @@ Panel queries and/or annotation queries that used more than one statistic will b - **InfluxDB:** InfluxQL: adds tags to timeseries data. [#36702](https://github.com/grafana/grafana/pull/36702), [@gabor](https://github.com/gabor) - **InfluxDB:** InfluxQL: make measurement search case insensitive. [#34563](https://github.com/grafana/grafana/pull/34563), [@gabor](https://github.com/gabor) - **Legacy Alerting:** Replace simplejson with a struct in webhook notification channel. [#34952](https://github.com/grafana/grafana/pull/34952), [@KEVISONG](https://github.com/KEVISONG) -- **Legend:** Updates display name for Last (not null) to just Last*. [#35633](https://github.com/grafana/grafana/pull/35633), [@torkelo](https://github.com/torkelo) +- **Legend:** Updates display name for Last (not null) to just Last\*. [#35633](https://github.com/grafana/grafana/pull/35633), [@torkelo](https://github.com/torkelo) - **Logs panel:** Add option to show common labels. [#36166](https://github.com/grafana/grafana/pull/36166), [@ivanahuckova](https://github.com/ivanahuckova) -- **Loki:** Add $__range variable. [#36175](https://github.com/grafana/grafana/pull/36175), [@ivanahuckova](https://github.com/ivanahuckova) +- **Loki:** Add $\_\_range variable. [#36175](https://github.com/grafana/grafana/pull/36175), [@ivanahuckova](https://github.com/ivanahuckova) - **Loki:** Add support for "label_values(log stream selector, label)" in templating. [#35488](https://github.com/grafana/grafana/pull/35488), [@ivanahuckova](https://github.com/ivanahuckova) - **Loki:** Add support for ad-hoc filtering in dashboard. [#36393](https://github.com/grafana/grafana/pull/36393), [@ivanahuckova](https://github.com/ivanahuckova) - **MySQL Datasource:** Add timezone parameter. [#27535](https://github.com/grafana/grafana/pull/27535), [@andipabst](https://github.com/andipabst) @@ -332,18 +328,16 @@ Panel queries and/or annotation queries that used more than one statistic will b ### Breaking changes - When parsing Elasticsearch query responses using template variables, each field gets named after the variable value instead of the name. For example, executing a `terms` aggregation on a variable named `$groupBy` that has `@hostname` as a value, the resulting column in the table response will be `@hostname` instead of `$groupBy` Issue [#36035](https://github.com/grafana/grafana/issues/36035) - Azure Monitor data source no longer supports different credentials for Metrics and Logs in existing data sources. To use different credentials for Azure Monitor Logs, create another data source. Issue [#35121](https://github.com/grafana/grafana/issues/35121) Existing Azure Metrics Logs queries for Log Analytics Workspaces should be backward compatible with this change and should not get impacted. Panels will be migrated to use the new resource-centric backend when you first edit and save them. Application Insights and Insights Analytics queries are now read-only and cannot be modified. To update Application Insights queries, users can manually recreate them as Metrics queries, and Insights Analytics are recreated with Logs. - Issue [#33879](https://github.com/grafana/grafana/issues/33879) +Issue [#33879](https://github.com/grafana/grafana/issues/33879) ### Plugin development fixes & changes @@ -560,7 +554,7 @@ The following endpoints were deprecated for Grafana v5.0 and support for them ha - **Admin:** Fix infinite loading edit on the profile page. [#34627](https://github.com/grafana/grafana/pull/34627), [@hugohaggmark](https://github.com/hugohaggmark) - **Color:** Fix issues with random colors in string and date fields. [#34913](https://github.com/grafana/grafana/pull/34913), [@torkelo](https://github.com/torkelo) - **Dashboard:** Fix issue with title or folder change has no effect after exiting settings view. [#34677](https://github.com/grafana/grafana/pull/34677), [@torkelo](https://github.com/torkelo) -- **DataLinks:** Fix an issue __series.name is not working in data link. [#34932](https://github.com/grafana/grafana/pull/34932), [@torkelo](https://github.com/torkelo) +- **DataLinks:** Fix an issue \_\_series.name is not working in data link. [#34932](https://github.com/grafana/grafana/pull/34932), [@torkelo](https://github.com/torkelo) - **Datasource:** Fix dataproxy timeout should always be applied for outgoing data source HTTP requests. [#34597](https://github.com/grafana/grafana/pull/34597), [@dsotirakis](https://github.com/dsotirakis) - **Elasticsearch:** Fix NewClient not passing httpClientProvider to client impl. [#34539](https://github.com/grafana/grafana/pull/34539), [@KiVirgil](https://github.com/KiVirgil) - **Explore:** Fix Browser title not updated on Navigation to Explore. [#34651](https://github.com/grafana/grafana/pull/34651), [@axelavargas](https://github.com/axelavargas) @@ -575,8 +569,7 @@ The following endpoints were deprecated for Grafana v5.0 and support for them ha ### Breaking changes - -The default HTTP method for Prometheus data source is now POST. Previously, it was GET. The POST APIs have been available since January 2018 (Prometheus 2.1.0) and they have fewer limitations than the GET APIs. For example, when dealing with high cardinality labels, GET hits the URL size limit. +The default HTTP method for Prometheus data source is now POST. Previously, it was GET. The POST APIs have been available since January 2018 (Prometheus 2.1.0) and they have fewer limitations than the GET APIs. For example, when dealing with high cardinality labels, GET hits the URL size limit. If you have a Prometheus instance with version < 2.1.0, which uses the default HTTP method, update your HTTP method to GET. Issue [#34599](https://github.com/grafana/grafana/issues/34599) diff --git a/CHANGELOG_ARCHIVE.md b/CHANGELOG_ARCHIVE.md index 68d0efd0405..6cc22ffe91a 100644 --- a/CHANGELOG_ARCHIVE.md +++ b/CHANGELOG_ARCHIVE.md @@ -1,4 +1,3 @@ - # 5.4.5 (2019-08-29) - **Security**: Urgent security patch release. Please read more in our [blog](https://grafana.com/blog/2019/08/29/grafana-5.4.5-and-6.3.4-released-with-important-security-fix/) @@ -180,7 +179,7 @@ See [security announcement](https://community.grafana.com/t/grafana-5-3-3-and-4- - **Alerting**: Link to view full size image in Microsoft Teams alert notifier [#13121](https://github.com/grafana/grafana/issues/13121), thx [@holiiveira](https://github.com/holiiveira) - **Alerting**: Fixes a bug where all alerts would send reminders after upgrade & restart [#13402](https://github.com/grafana/grafana/pull/13402) - **Alerting**: Concurrent render limit for graphs used in notifications [#13401](https://github.com/grafana/grafana/pull/13401) -- **Postgres/MySQL/MSSQL**: Add support for replacing $__interval and $\_\_interval_ms in alert queries [#11555](https://github.com/grafana/grafana/issues/11555), thx [@svenklemm](https://github.com/svenklemm) +- **Postgres/MySQL/MSSQL**: Add support for replacing $\_\_interval and $\_\_interval_ms in alert queries [#11555](https://github.com/grafana/grafana/issues/11555), thx [@svenklemm](https://github.com/svenklemm) # 5.3.0-beta1 (2018-09-06) @@ -214,18 +213,18 @@ See [security announcement](https://community.grafana.com/t/grafana-5-3-3-and-4- - **OAuth**: Fix overriding tls_skip_verify_insecure using environment variable [#12747](https://github.com/grafana/grafana/issues/12747), thx [@jangaraj](https://github.com/jangaraj) - **Prometheus**: Fix graph panel bar width issue in aligned prometheus queries [#12379](https://github.com/grafana/grafana/issues/12379) - **Prometheus**: Heatmap - fix unhandled error when some points are missing [#12484](https://github.com/grafana/grafana/issues/12484) -- **Prometheus**: Add $__interval, $**interval_ms, \$**range, $__range_s & $\_\_range_ms support for dashboard and template queries [#12597](https://github.com/grafana/grafana/issues/12597) [#12882](https://github.com/grafana/grafana/issues/12882), thx [@roidelapluie](https://github.com/roidelapluie) +- **Prometheus**: Add $**interval, $**interval_ms, \$**range, $**range_s & $\_\_range_ms support for dashboard and template queries [#12597](https://github.com/grafana/grafana/issues/12597) [#12882](https://github.com/grafana/grafana/issues/12882), thx [@roidelapluie](https://github.com/roidelapluie) - **Elasticsearch**: For alerting/backend, support having index name to the right of pattern in index pattern [#12731](https://github.com/grafana/grafana/issues/12731) - **Graphite**: Fix for quoting of int function parameters (when using variables) [#11927](https://github.com/grafana/grafana/pull/11927) - **InfluxDB**: Support timeFilter in query templating for InfluxDB [#12598](https://github.com/grafana/grafana/pull/12598), thx [kichristensen](https://github.com/kichristensen) -- **Postgres/MySQL/MSSQL**: New $__unixEpochGroup and $\_\_unixEpochGroupAlias macros [#12892](https://github.com/grafana/grafana/issues/12892), thx [@svenklemm](https://github.com/svenklemm) +- **Postgres/MySQL/MSSQL**: New $\_\_unixEpochGroup and $\_\_unixEpochGroupAlias macros [#12892](https://github.com/grafana/grafana/issues/12892), thx [@svenklemm](https://github.com/svenklemm) - **Postgres/MySQL/MSSQL**: Add previous fill mode to \$\_\_timeGroup macro which will fill in previously seen value when point is missing [#12756](https://github.com/grafana/grafana/issues/12756), thx [@svenklemm](https://github.com/svenklemm) - **Postgres/MySQL/MSSQL**: Use floor rounding in \$\_\_timeGroup macro function [#12460](https://github.com/grafana/grafana/issues/12460), thx [@svenklemm](https://github.com/svenklemm) - **Postgres/MySQL/MSSQL**: Use metric column as prefix when returning multiple value columns [#12727](https://github.com/grafana/grafana/issues/12727), thx [@svenklemm](https://github.com/svenklemm) -- **Postgres/MySQL/MSSQL**: New $__timeGroupAlias macro. Postgres $\_\_timeGroup no longer automatically adds time column alias [#12749](https://github.com/grafana/grafana/issues/12749), thx [@svenklemm](https://github.com/svenklemm) +- **Postgres/MySQL/MSSQL**: New $\_\_timeGroupAlias macro. Postgres $\_\_timeGroup no longer automatically adds time column alias [#12749](https://github.com/grafana/grafana/issues/12749), thx [@svenklemm](https://github.com/svenklemm) - **Postgres/MySQL/MSSQL**: Escape single quotes in variables [#12785](https://github.com/grafana/grafana/issues/12785), thx [@eMerzh](https://github.com/eMerzh) - **Postgres/MySQL/MSSQL**: Min time interval support [#13157](https://github.com/grafana/grafana/issues/13157), thx [@svenklemm](https://github.com/svenklemm) -- **MySQL/MSSQL**: Use datetime format instead of epoch for $__timeFilter, $**timeFrom and \$**timeTo macros [#11618](https://github.com/grafana/grafana/issues/11618) [#11619](https://github.com/grafana/grafana/issues/11619), thx [@AustinWinstanley](https://github.com/AustinWinstanley) +- **MySQL/MSSQL**: Use datetime format instead of epoch for $\_\_timeFilter, $**timeFrom and \$**timeTo macros [#11618](https://github.com/grafana/grafana/issues/11618) [#11619](https://github.com/grafana/grafana/issues/11619), thx [@AustinWinstanley](https://github.com/AustinWinstanley) - **Postgres**: Escape ssl mode parameter in connectionstring [#12644](https://github.com/grafana/grafana/issues/12644), thx [@yogyrahmawan](https://github.com/yogyrahmawan) - **Cloudwatch**: Improved error handling [#12489](https://github.com/grafana/grafana/issues/12489), thx [@mtanda](https://github.com/mtanda) - **Cloudwatch**: AppSync metrics and dimensions [#12300](https://github.com/grafana/grafana/issues/12300), thx [@franciscocpg](https://github.com/franciscocpg) @@ -1019,7 +1018,7 @@ Pull Request: [#8472](https://github.com/grafana/grafana/pull/8472) ## Enhancements - **Telegram**: Added Telegram alert notifier [#7098](https://github.com/grafana/grafana/pull/7098), thx [@leonoff](https://github.com/leonoff) -- **Templating**: Make $__interval and $\_\_interval_ms global built in variables that can be used in by any data source (in panel queries), closes [#7190](https://github.com/grafana/grafana/issues/7190), closes [#6582](https://github.com/grafana/grafana/issues/6582) +- **Templating**: Make $\_\_interval and $\_\_interval_ms global built in variables that can be used in by any data source (in panel queries), closes [#7190](https://github.com/grafana/grafana/issues/7190), closes [#6582](https://github.com/grafana/grafana/issues/6582) - **S3 Image Store**: External s3 image store (used in alert notifications) now support AWS IAM Roles, closes [#6985](https://github.com/grafana/grafana/issues/6985), [#7058](https://github.com/grafana/grafana/issues/7058) thx [@mtanda](https://github.com/mtanda) - **SingleStat**: Implements diff aggregation method for singlestat [#7234](https://github.com/grafana/grafana/issues/7234), thx [@oliverpool](https://github.com/oliverpool) - **Dataproxy**: Added setting to enable more verbose logging in dataproxy [#7209](https://github.com/grafana/grafana/pull/7209), thx [@Ricky-N](https://github.com/Ricky-N) diff --git a/ISSUE_TRIAGE.md b/ISSUE_TRIAGE.md index 99dbcf970d1..22d9409fe8d 100644 --- a/ISSUE_TRIAGE.md +++ b/ISSUE_TRIAGE.md @@ -4,7 +4,7 @@ The main goal of issue triage is to categorize all incoming Grafana issues and m > **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. -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. +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: @@ -18,6 +18,7 @@ If you don't have the knowledge or time to code, consider helping with triage. T ## Simplified flowchart diagram of the issue triage process + ``` +--------------------------+ +----------------+ New issue opened/ | @@ -76,15 +77,16 @@ Instructions for setting up filters in Gmail can be found [here](#setting-up-gma ## 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://help.github.com/en/articles/creating-issue-templates-for-your-repository) to guide contributors to provide standard information that must be included for each type of template or type of issue. +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://help.github.com/en/articles/creating-issue-templates-for-your-repository) to guide contributors to provide standard information that must be included for each type of template or type of issue. ### Standard issue information that must be included -Given a certain [issue template]([template](https://github.com/grafana/grafana/issues/new/choose)) have been used by the issue author or depending how the issue is perceived by the issue triage responsible, the following should help you understand what standard issue information that must be included. +Given a certain [issue template](<[template](https://github.com/grafana/grafana/issues/new/choose)>) have been used by the issue author or depending how the issue is perceived by the issue triage responsible, the following should help you understand what standard issue information that must be included. #### 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: + - Grafana version - Data source type & version - Platform & OS Grafana is installed on @@ -170,10 +172,12 @@ If it's not perfectly clear that it's an actual bug, quickly try to reproduce it 4. 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. **It works as intended/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`. @@ -195,6 +199,7 @@ Second, label the issue `type/docs` and at least one `area/*` or `datasource/*` **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: + 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. @@ -299,12 +304,12 @@ For some other combinations it may not be possible at all for a maintainer to se Even if you don't have the time or knowledge to investigate an issue we highly recommend that you [upvote](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments) the issue if you happen to have the same problem. If you have further details that may help investigating the issue please provide as much information as possible. -## 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) -* Add /duplicate `#` to have Grafana label & close issue with an appropriate message. -* Add `bot/question` and the bot will close it with an appropriate message. +- Add /duplicate `#` to have Grafana label & close issue 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/main/.github/bot.md) @@ -324,6 +329,7 @@ Part of issue triage should also be triaging of external PRs. Main goal should b 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. This may be setup 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 @@ -332,6 +338,7 @@ This may be setup by personal preference, but here's a working configuration for 6. Create filters This will give you a structure of labels in the sidebar similar to the following: + ``` - Inbox ... diff --git a/NOTICE.md b/NOTICE.md index 40cf840d2a8..15bc6c61bf3 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -1,6 +1,4 @@ - Copyright 2014-2021 Grafana Labs -This software is based on Kibana: +This software is based on Kibana: Copyright 2012-2013 Elasticsearch BV - diff --git a/PLUGIN_DEV.md b/PLUGIN_DEV.md index 27ddacfc315..e33c8047e57 100644 --- a/PLUGIN_DEV.md +++ b/PLUGIN_DEV.md @@ -1,8 +1,8 @@ -# Plugin development +# Plugin development This document is not meant as a complete guide for developing plugins but more as a changelog for changes in Grafana that can impact plugin development. Whenever you as a plugin author encounter an issue with your plugin after -upgrading Grafana please check here before creating an issue. +upgrading Grafana please check here before creating an issue. ## Plugin development resources @@ -13,15 +13,15 @@ upgrading Grafana please check here before creating an issue. ## Changes in Grafana v4.6 This version of Grafana has big changes that will impact a limited set of plugins. We moved from systemjs to webpack -for built-in plugins and everything internal. External plugins still use systemjs but now with a limited -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. +for built-in plugins and everything internal. External plugins still use systemjs but now with a limited +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. [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. -### Deprecated components +### Deprecated components The angular directive `` is now deprecated (will still work for a version more) but we recommend plugin authors upgrade to new `` diff --git a/ROADMAP.md b/ROADMAP.md index d0e69b013f9..7daf6465dcc 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ # Roadmap -The roadmap is a tentative plan for the core development team. Things change constantly as pull requests come in and priorities change, but it will give you an idea of our current vision and plan. - +The roadmap is a tentative plan for the core development team. Things change constantly as pull requests come in and priorities change, but it will give you an idea of our current vision and plan. + To view the Roadmap, go to the Issues tab on GitHub. There you will find three roadmap issues pinned at the top. diff --git a/SECURITY.md b/SECURITY.md index 355a58811dc..b0577534339 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,10 +1,10 @@ # Reporting security issues -If you think you have found a security vulnerability, please send a report to [security@grafana.com](mailto:security@grafana.com). This address can be used for all of Grafana Labs's open source and commercial products (including but not limited to Grafana, Grafana Cloud, Grafana Enterprise, and grafana.com). We can accept only vulnerability reports at this address. +If you think you have found a security vulnerability, please send a report to [security@grafana.com](mailto:security@grafana.com). This address can be used for all of Grafana Labs's open source and commercial products (including but not limited to Grafana, Grafana Cloud, Grafana Enterprise, and grafana.com). We can accept only vulnerability reports at this address. Please encrypt your message to us; please use our PGP key. The key fingerprint is: -F988 7BEA 027A 049F AE8E 5CAA D125 8932 BE24 C5CA +F988 7BEA 027A 049F AE8E 5CAA D125 8932 BE24 C5CA The key is available from [keyserver.ubuntu.com](https://keyserver.ubuntu.com/pks/lookup?search=0xF9887BEA027A049FAE8E5CAAD1258932BE24C5CA&fingerprint=on&op=index). @@ -15,6 +15,6 @@ Grafana Labs will send you a response indicating the next steps in handling your ## Security announcements We maintain a category on the community site called [Security Announcements](https://community.grafana.com/c/security-announcements), -where we will post a summary, remediation, and mitigation details for any patch containing security fixes. +where we will post a summary, remediation, and mitigation details for any patch containing security fixes. You can also subscribe to email updates to this category if you have a grafana.com account and sign on to the community site or track updates via an [RSS feed](https://community.grafana.com/c/security-announcements.rss). diff --git a/SUPPORT.md b/SUPPORT.md index c9c94d96a49..a8aae994618 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,10 +1,13 @@ # Get Grafana help ------------------- + +--- + First, check the official [Grafana documentation](https://grafana.com/docs/). If you require further help or support then ask a question in the [Grafana community site](https://community.grafana.com/) or [Grafana Slack](http://slack.raintank.io/). You can also search the community site for previously answered questions, in case someone already had your problem and got help. - **Please note:** +**Please note:** + - The Grafana project uses GitHub mainly for tracking bugs and feature requests. - Do not open an issue just to ask a question. The issue will be closed immediately. - Only submit issues for bug reports, feature requests, or enhancements. diff --git a/WORKFLOW.md b/WORKFLOW.md index d369eb67ae2..633a996cf6a 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -13,6 +13,7 @@ Team members and their access to repositories is maintained through [GitHub team ## 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 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. - Issue - Developer mailing list @@ -24,6 +25,7 @@ Significant changes MUST be discussed and agreed upon with the relevant subsyste 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 main using PRs. They MUST NOT be merged into main directly. + - Every merge MUST be approved by at least one team member. - Non-trivial changes MUST be approved by at least - two team members, or @@ -33,6 +35,7 @@ Commits MUST be merged into main using PRs. They MUST NOT be merged into main di - the relevant subsystem maintainer. PRs MUST be [reviewed](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests) and [approved](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews) via GitHub’s review system. + - Reviewers MAY write comments if approving - Reviewers MUST write comments if rejecting a PR or if requesting changes. @@ -40,9 +43,9 @@ Once a PR is approved as per above, any team member MAY merge the 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/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. +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. # Release workflow @@ -51,6 +54,7 @@ Backport PRs are also needed during the beta period to get fixes into the stable Grafana uses trunk-based development. In particular, we found that the following principles match how we work: + - 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. - Changes MAY be enabled by default once they are in a complete state @@ -61,6 +65,7 @@ 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. Release branches MUST be split from the following branches. + - MAJOR release branches MUST be based on main. - MINOR release branches MUST be based on main. - PATCH release branches MUST be split from the relevant MINOR release branch’s most current PATCH @@ -68,6 +73,7 @@ Release branches MUST be split from the following branches. 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. Releases follow the following cadence + - MAJOR: Yearly - MINOR: Every 4-6 weeks - PATCH: As needed diff --git a/contribute/architecture/README.md b/contribute/architecture/README.md index d3ccbb37251..27c43893e4a 100644 --- a/contribute/architecture/README.md +++ b/contribute/architecture/README.md @@ -4,10 +4,10 @@ Are you looking to take on contributions with bigger impact? These guides help y Learn more about the backend architecture: -- Part 1: [Services](backend/services.md) +- Part 1: [Services](backend/services.md) - Part 2: [Communication](backend/communication.md) - Part 3: [Database](backend/database.md) Learn more about the frontend architecture: -- Part 1: [Data requests](frontend-data-requests.md) +- Part 1: [Data requests](frontend-data-requests.md) diff --git a/contribute/architecture/backend/package-hierarchy.md b/contribute/architecture/backend/package-hierarchy.md index 47daab6aa57..d940910cdd0 100644 --- a/contribute/architecture/backend/package-hierarchy.md +++ b/contribute/architecture/backend/package-hierarchy.md @@ -1,12 +1,12 @@ # Package hierarchy The Go package hierarchy in Grafana should be organized logically (Ben Johnson's -[article](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1) served as inspiration), according to the +[article](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1) served as inspiration), according to the following principles: -* Domain types and interfaces should be in "root" packages (not necessarily at the very top, of the hierarchy, but +- Domain types and interfaces should be in "root" packages (not necessarily at the very top, of the hierarchy, but logical roots) -* Sub-packages should depend on roots - sub-packages here typically contain implementations, for example of services +- Sub-packages should depend on roots - sub-packages here typically contain implementations, for example of services ## Practical example diff --git a/contribute/architecture/frontend-data-requests.md b/contribute/architecture/frontend-data-requests.md index ce75982d308..f14f22c4749 100644 --- a/contribute/architecture/frontend-data-requests.md +++ b/contribute/architecture/frontend-data-requests.md @@ -3,6 +3,7 @@ [BackendSrv](https://grafana.com/docs/grafana/latest/packages_api/runtime/backendsrv) handles all outgoing HTTP requests from Grafana. This document explains the high-level concepts used by `BackendSrv`. ## Canceling requests + This section describes how canceling requests work in Grafana. While data sources can implement their own cancellation concept, we recommend that you use the method we describe here. A data request can take a long time to finish. During the time between when a request starts and finishes, the user can change context. For example, the user may navigate away or issue the same request again. @@ -12,29 +13,35 @@ 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. #### 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/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: + - 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 the special "cancel all requests" `requestId` was sent, then Grafana will cancel the ongoing request. #### After Grafana 7.2 + Grafana 7.2 introduced an additional way of canceling requests using [RxJs](https://github.com/ReactiveX/rxjs). To support the new cancellation functionality, the data source needs to use the new `fetch` function in [BackendSrv](https://grafana.com/docs/grafana/latest/packages_api/runtime/backendsrv). Migrating the core data sources to the new `fetch` function [is an ongoing process that you can read about in this issue.](https://github.com/grafana/grafana/issues/27222) ## Request queue -Depending on how the web browser implements the protocol for HTTP 1.1, it will limit the number of parallel requests, lets call this limit _max_parallel_browser_request_. + +Depending on how the web browser implements the protocol for HTTP 1.1, it will limit the number of parallel requests, lets call this limit _max_parallel_browser_request_. Unless you have configured Grafana to use HTTP2, the browser limits parallel data requests according to the browser's implementation. For more information on how to enable HTTP2, refer to [Configuration](https://grafana.com/docs/grafana/latest/administration/configuration/#protocol). Because there is a _max_parallel_browser_request_ limit, if some of the requests take a long time, they will block later requests and make interacting with Grafana very slow. #### Before Grafana 7.2 -Not supported. + +Not supported. #### After Grafana 7.2 -Grafana uses a _request queue_ to process all incoming data requests in order while reserving a free "spot" for any requests to the Grafana API. + +Grafana uses a _request queue_ to process all incoming data requests in order while reserving a free "spot" for any requests to the Grafana API. Since the first implementation of the request queue doesn't take into account what browser the user uses, the _request queue_ limit for parallel data source requests is hard-coded to 5. diff --git a/contribute/engineering/backend/upgrading-dependencies.md b/contribute/engineering/backend/upgrading-dependencies.md index c56e293d574..5f011ec2b9b 100644 --- a/contribute/engineering/backend/upgrading-dependencies.md +++ b/contribute/engineering/backend/upgrading-dependencies.md @@ -17,6 +17,6 @@ mage protobuf After upgrading the protobuf dependency in Grafana and the plugin SDK, it might be wise to test that things still work, before making corresponding PRs: -* Test a plugin built with upgraded SDK on upgraded Grafana -* Test a plugin built with non-upgraded SDK on upgraded Grafana -* Test a plugin built with upgraded SDK on non-upgraded Grafana +- Test a plugin built with upgraded SDK on upgraded Grafana +- Test a plugin built with non-upgraded SDK on upgraded Grafana +- Test a plugin built with upgraded SDK on non-upgraded Grafana diff --git a/contribute/engineering/terminology.md b/contribute/engineering/terminology.md index 756a3c032dd..4a833dd7fb2 100644 --- a/contribute/engineering/terminology.md +++ b/contribute/engineering/terminology.md @@ -6,12 +6,12 @@ This document defines technical terms used in Grafana. ## TLS/SSL -The acronyms [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) (Transport Layer Security and +The acronyms [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) (Transport Layer Security and [SSL](https://en.wikipedia.org/wiki/SSL) (Secure Socket Layer) are both used to describe the HTTPS security layer, and are in practice synonymous. However, TLS is considered the current name for the technology, and SSL is considered -[deprecated](https://tools.ietf.org/html/rfc7568). +[deprecated](https://tools.ietf.org/html/rfc7568). -As such, while both terms are in use (also in our codebase) and are indeed interchangeable, TLS is the preferred term. -That said however, we have at Grafana Labs decided to use both acronyms in combination when referring to this type of +As such, while both terms are in use (also in our codebase) and are indeed interchangeable, TLS is the preferred term. +That said however, we have at Grafana Labs decided to use both acronyms in combination when referring to this type of technology, i.e. _TLS/SSL_. This is in order to not confuse those who may not be aware of them being synonymous, and SSL still being so prevalent in common discourse. diff --git a/contribute/style-guides/backend.md b/contribute/style-guides/backend.md index 215b9ef8718..351f317c812 100644 --- a/contribute/style-guides/backend.md +++ b/contribute/style-guides/backend.md @@ -42,8 +42,8 @@ In the `sqlstore` package we do database operations in tests and while some migh ### Assertions -Use respectively [`assert.*`](https://github.com/stretchr/testify#assert-package) functions to make assertions that -should _not_ halt the test ("soft checks") and [`require.*`](https://github.com/stretchr/testify#require-package) +Use respectively [`assert.*`](https://github.com/stretchr/testify#assert-package) functions to make assertions that +should _not_ halt the test ("soft checks") and [`require.*`](https://github.com/stretchr/testify#require-package) functions to make assertions that _should_ halt the test ("hard checks"). Typically you want to use the latter type of check to assert that errors have or have not happened, since continuing the test after such an assertion fails is chaotic (the system under test will be in an undefined state) and you'll often have segfaults in practice. @@ -70,10 +70,10 @@ In general, use value types and only reach for pointers when there's a real need increase the risk of bugs, since a pointer can be nil and dereferencing a nil pointer leads to a panic (AKA segfault). Valid reasons to use a pointer include (but not necessarily limited to): -* You might need to pass a modifiable argument to a function -* Copying an object might incur a performance hit (benchmark to check your assumptions, copying is often faster than +- You might need to pass a modifiable argument to a function +- Copying an object might incur a performance hit (benchmark to check your assumptions, copying is often faster than allocating heap memory) -* You might *need* `nil` to tell if a variable isn't set, although usually it's better to use the type's zero +- You might _need_ `nil` to tell if a variable isn't set, although usually it's better to use the type's zero value to tell instead ## Database @@ -83,7 +83,7 @@ In database related code, we follow certain patterns. ### Foreign keys While they can be useful, we don't generally use foreign key constraints in Grafana, for historical and -technical reasons. See this [comment](https://github.com/grafana/grafana/issues/3269#issuecomment-383328548) by Torkel +technical reasons. See this [comment](https://github.com/grafana/grafana/issues/3269#issuecomment-383328548) by Torkel for context. ### Unique columns @@ -93,7 +93,7 @@ If a column, or column combination, should be unique, add a corresponding unique ## JSON The simplejson package is used a lot throughout the backend codebase, but it's legacy, so if at all possible -avoid using it in new code. Use [json-iterator](https://github.com/json-iterator/go) instead, which is a more performant +avoid using it in new code. Use [json-iterator](https://github.com/json-iterator/go) instead, which is a more performant drop-in alternative to the standard [encoding/json](https://golang.org/pkg/encoding/json/) package. While encoding/json is a fine choice, profiling shows that json-iterator may be 3-4 times more efficient for encoding. We haven't profiled its parsing performance yet, but according to json-iterator's own benchmarks, it appears even more superior in this diff --git a/contribute/style-guides/code-comments.md b/contribute/style-guides/code-comments.md index cff0f798b53..b110e4a7313 100644 --- a/contribute/style-guides/code-comments.md +++ b/contribute/style-guides/code-comments.md @@ -1,4 +1,4 @@ -# Guidelines for code comments in grafana-* packages +# Guidelines for code comments in grafana-\* packages This document aims to give you some recommendation on how to add code comments to the exported code in the grafana packages. @@ -9,11 +9,12 @@ This document aims to give you some recommendation on how to add code comments t 1. [Deprecate an API](#deprecate-an-api) 1. [Specify parameters](#specify-parameters) 1. [Set return values](#set-return-values) -____ - ## Add package description +--- -Each package has an overview explaining the overall responsibility and usage of the package. +## Add package description + +Each package has an overview explaining the overall responsibility and usage of the package. You can document this description with [`@packageDocumentation`](https://api-extractor.com/pages/tsdoc/tag_packagedocumentation/) tag. @@ -32,33 +33,34 @@ All `exported` apis from the package should have a release tag to indicate its s Add a tag to mark the stability of the whole exported `class/interface/function/type` etc. -Please place the `release tag` at the bottom of the comment to make it consistent among files and easier to read. +Please place the `release tag` at the bottom of the comment to make it consistent among files and easier to read. **Do:** -```typescript +````typescript /** - * Will help to create DataFrame objects and handle + * Will help to create DataFrame objects and handle * the heavy lifting of creating a complex object. - * + * * @example * ```typescript * const dataFrame = factory.create(); * ``` - * + * * @public **/ export class DataFrameFactory { - create(): DataFrame { } + create(): DataFrame {} } -``` +```` **Don't** -```typescript + +````typescript /** - * Will help to create DataFrame objects and handle + * Will help to create DataFrame objects and handle * the heavy lifting of creating a complex object. - * + * * @public * @example * ```typescript @@ -66,9 +68,9 @@ export class DataFrameFactory { * ``` **/ export class DataFrameFactory { - create(): DataFrame { } + create(): DataFrame {} } -``` +```` ### Partial stability of APIs @@ -78,59 +80,61 @@ Then override the non-stable parts of the API with the proper [release tag](#rel **Do:** -```typescript +````typescript /** - * Will help to create DataFrame objects and handle + * Will help to create DataFrame objects and handle * the heavy lifting of creating a complex object. - * + * * @example * ```typescript * const dataFrame = factory.create(); * ``` - * + * * @public **/ export class DataFrameFactory { - create(): DataFrame { } + create(): DataFrame {} - /** - * @beta - **/ - createMany(): DataFrames[] {} + /** + * @beta + **/ + createMany(): DataFrames[] {} } -``` +```` **Don't** -```typescript +````typescript /** - * Will help to create DataFrame objects and handle + * Will help to create DataFrame objects and handle * the heavy lifting of creating a complex object. - * + * * @example * ```typescript * const dataFrame = factory.create(); * ``` **/ export class DataFrameFactory { - /** - * @public - **/ - create(): DataFrame { } + /** + * @public + **/ + create(): DataFrame {} - /** - * @beta - **/ - createMany(): DataFrame[] {} + /** + * @beta + **/ + createMany(): DataFrame[] {} } -``` +```` ## Deprecate an API + If you want to mark an API as deprecated to signal that this API will be removed in the future, then add the [`@deprecated`](https://api-extractor.com/pages/tsdoc/tag_deprecated/) tag. If applicable add a reason why the API is deprecated directly after the `@deprecated tag`. ## Specify parameters + If you want to specify the possible parameters that can be passed to an API, then add the [`@param`](https://api-extractor.com/pages/tsdoc/tag_param/) tag. This attribute can be skipped if the type provided by `typescript` and the function comment or the function name is enough to explain what the parameters are. @@ -141,17 +145,17 @@ This attribute can be skipped if the type provided by `typescript` and the funct /** * Will help to create a resource resolver depending * on the current execution context. - * + * * @param context - The current execution context. * @returns FileResolver if executed on the server otherwise a HttpResolver. * @public **/ export const factory = (context: Context): IResolver => { - if (context.isServer) { - return new FileResolver(); - } - return new HttpResolver(); -} + if (context.isServer) { + return new FileResolver(); + } + return new HttpResolver(); +}; ``` **Don't** @@ -159,18 +163,18 @@ export const factory = (context: Context): IResolver => { ```typescript /** * Will compare two numbers to see if they are equal to each others. - * + * * @param x - The first number * @param y - The second number * @public **/ export const isEqual = (x: number, y: number): boolean => { - return x === y; -} + return x === y; +}; ``` - ## Set return values + If you want to specify the return value from a function you can use the [`@returns`](https://api-extractor.com/pages/tsdoc/tag_returns/) tag. This attribute can be skipped if the type provided by `typescript` and the function comment or the function name is enough to explain what the function returns. @@ -181,17 +185,17 @@ This attribute can be skipped if the type provided by `typescript` and the funct /** * Will help to create a resource resolver depending * on the current execution context. - * + * * @param context - The current execution context. * @returns FileResolver if executed on the server otherwise a HttpResolver. * @public **/ export const factory = (context: Context): IResolver => { - if (context.isServer) { - return new FileResolver(); - } - return new HttpResolver(); -} + if (context.isServer) { + return new FileResolver(); + } + return new HttpResolver(); +}; ``` **Don't** @@ -199,11 +203,11 @@ export const factory = (context: Context): IResolver => { ```typescript /** * Will compare two numbers to see if they are equal to each others. - * + * * @returns true if values are equal * @public **/ export const isEqual = (x: number, y: number): boolean => { - return x === y; -} + return x === y; +}; ``` diff --git a/contribute/style-guides/documentation-markdown-guide.md b/contribute/style-guides/documentation-markdown-guide.md index a17315968b6..b22c1db888b 100644 --- a/contribute/style-guides/documentation-markdown-guide.md +++ b/contribute/style-guides/documentation-markdown-guide.md @@ -12,19 +12,18 @@ In Markdown, the number of "#" symbols creates different heading levels, similar - \#\# is \

. - \#\#\# is \

. -Start your document with a single ``#`` for the title of the page. Add the sub-headings with two ``##``. +Start your document with a single `#` for the title of the page. Add the sub-headings with two `##`. ## Bold and emphasis - Make text **bold** using two asterisks. -**Example:** It is ``**important**`` to use GitHub-flavored Markdown emoji consistently. +**Example:** It is `**important**` to use GitHub-flavored Markdown emoji consistently. -- Make text ``_emphasized_`` using single `` _underscores_``. Do not use the single asterisk, it can be easily confused with bold. +- Make text `_emphasized_` using single ` _underscores_`. Do not use the single asterisk, it can be easily confused with bold. **Example:** GitHub-flavored markdown emoji should _only_ appear in specific cases. - ## Links and references Create links to other website by wrapping the display text in square brackets, and the web URL in curved brackets. @@ -62,12 +61,13 @@ Write the name of the language after the first set of back tics, no spaces, to s ```javascript function testNum(a) { if (a > 0) { - return "positive"; + return 'positive'; } else { - return "NOT positive"; + return 'NOT positive'; } } ``` + ## Tables Construct a table by typing the table headings, and separating them with a "|" character. Then, add a second line of dashes ("-") separated by another "|" character. When constructing the table cells, separate each cell data with another "|". @@ -82,9 +82,9 @@ Cell one data| Cell two data Will publish as: -Heading one | Heading two -------------|------------ -Cell one data| Cell two data +| Heading one | Heading two | +| ------------- | ------------- | +| Cell one data | Cell two data | ## Lists @@ -126,7 +126,7 @@ Include images in a document using the following syntax: > **Note:** Alt text does not appear when the user hovers the mouse over the image, but title text does. -**Examples:** +**Examples:** - \!\[Grafana logo](/link/to/grafanalogo/logo.png) - \!\[Example](/img/docs/folder_name/alert_test_rule.png) @@ -134,6 +134,7 @@ Include images in a document using the following syntax: This follows the format of "!", alt text wrapped in "[]" and the link URL wrapped in "()". You can also use HTML such as the following: + ``` Example image/e2e_](../../e2e) ## Test suites -All the integration tests are located at _\/e2e/suite\/specs_. The page objects and reusable flows are in the [_\/packages/grafana-e2e_](../../packages/grafana-e2e) package. +All the integration tests are located at _\/e2e/suite\/specs_. The page objects and reusable flows are in the [_\/packages/grafana-e2e_](../../packages/grafana-e2e) package. diff --git a/contribute/style-guides/redux.md b/contribute/style-guides/redux.md index 21d75964a47..5952b706ddf 100644 --- a/contribute/style-guides/redux.md +++ b/contribute/style-guides/redux.md @@ -1,6 +1,7 @@ # Redux framework Grafana uses [Redux Toolkit](https://redux-toolkit.js.org/) to handle Redux boilerplate code. + > Some of our Reducers are used by Angular and therefore state is to be considered as mutable for those reducers. ## Test functionality @@ -19,6 +20,7 @@ reducerTester() ``` #### Complex usage + Sometimes you encounter a `resulting state` that contains properties that are hard to compare, such as `Dates`, but you still want to compare that other props in state are correct. Then you can use `thenStatePredicateShouldEqual` function on `reducerTester` that will return the `resulting state` so that you can expect upon individual properties.. @@ -27,9 +29,9 @@ Then you can use `thenStatePredicateShouldEqual` function on `reducerTester` tha reducerTester() .givenReducer(someReducer, initialState) .whenActionIsDispatched(someAction('reducer tests')) - .thenStatePredicateShouldEqual(resultingState => { + .thenStatePredicateShouldEqual((resultingState) => { expect(resultingState.data).toEqual('reducer tests'); - return true; + return true; }); ``` @@ -40,9 +42,7 @@ Fluent API that simplifies the testing of thunks. #### Usage ```typescript -const dispatchedActions = await thunkTester(initialState) - .givenThunk(someThunk) - .whenThunkIsDispatched(arg1, arg2, arg3); +const dispatchedActions = await thunkTester(initialState).givenThunk(someThunk).whenThunkIsDispatched(arg1, arg2, arg3); expect(dispatchedActions).toEqual([someAction('reducer tests')]); ``` @@ -52,7 +52,7 @@ expect(dispatchedActions).toEqual([someAction('reducer tests')]); It is possible to infer connected props automatically from `mapStateToProps` and `mapDispatchToProps` using a helper type `ConnectedProps` from Redux. For this to work the `connect` call has to be split into two parts. ```typescript -import { connect, ConnectedProps } from 'react-redux' +import { connect, ConnectedProps } from 'react-redux'; const mapStateToProps = (state: StoreState) => { return { @@ -75,8 +75,9 @@ const connector = connect(mapStateToProps, mapDispatchToProps); type Props = OwnProps & ConnectedProps; -class PanelEditorUnconnected extends PureComponent {}; +class PanelEditorUnconnected extends PureComponent {} export const PanelEditor = connector(PanelEditorUnconnected); ``` + For more examples, refer to the [Redux docs](https://react-redux.js.org/using-react-redux/static-typing#inferring-the-connected-props-automatically). diff --git a/contribute/templates/README.md b/contribute/templates/README.md index 0fee55fea58..7b562678db6 100644 --- a/contribute/templates/README.md +++ b/contribute/templates/README.md @@ -15,34 +15,37 @@ Feel free to add templates to the `templates` folder. Try to make them as generi ## Documentation templates -In an ideal world, each topic will correspond to an information *type* ([task](doc-task-template.md), [reference](doc-reference-template.md), [concept](doc-concept-template.md)) and contain only that type of information. +In an ideal world, each topic will correspond to an information _type_ ([task](doc-task-template.md), [reference](doc-reference-template.md), [concept](doc-concept-template.md)) and contain only that type of information. However, this is not always practical. For example, you have a series of short topics, you can group them into one topic. -Try to *chunk* your content. This means you should organize the document so that the same kinds of content are grouped together. +Try to _chunk_ your content. This means you should organize the document so that the same kinds of content are grouped together. ### Chunking example -If I was writing content for a site called *Doggie handbook*, I might organize it like this. +If I was writing content for a site called _Doggie handbook_, I might organize it like this. **Concept** + - What a dog is - Brief history of dogs - Why you might want a dog - Tasks dogs can be trained to do - + **Tasks** + - Feed the dog - Groom the dog - Train the dog **Reference** + - List of dog equipment you will need - Table of breeds that includes breed name, size range, short or long hair, and type of dog ### Audience -Write for an audience that is computer literate and has general technical knowledge, but is not necessarily familiar with Grafana or the finer points of observability. +Write for an audience that is computer literate and has general technical knowledge, but is not necessarily familiar with Grafana or the finer points of observability. Pretend you are explaining your topic to a brand new Grafana user or developer. @@ -50,7 +53,7 @@ Pretend you are explaining your topic to a brand new Grafana user or developer. Thanks to search engines, every page in the documentation might be a reader's entry point. This means that each page needs to be self-contained and make sense on its own. The reader should not need to read other topics in order to perform the task or understand the concept. -However, try to be helpful and link to related information. Using the *Doggie handbook* example, the concept topic that explains what dogs can be trained to do might link to the Train the dog task. +However, try to be helpful and link to related information. Using the _Doggie handbook_ example, the concept topic that explains what dogs can be trained to do might link to the Train the dog task. ## Code templates diff --git a/contribute/templates/doc-concept-template.md b/contribute/templates/doc-concept-template.md index fd21e18aaa3..ea323e5a228 100644 --- a/contribute/templates/doc-concept-template.md +++ b/contribute/templates/doc-concept-template.md @@ -23,20 +23,20 @@ Concepts are topic types for any information that doesn't involve task lists or ## Idea -Concept topics or sections explain *what* and *why*. They do not explain *how*. If you are a new user, you might look for concept information to learn about what Grafana is, why it might be useful to you, and what the general workflow is. +Concept topics or sections explain _what_ and _why_. They do not explain _how_. If you are a new user, you might look for concept information to learn about what Grafana is, why it might be useful to you, and what the general workflow is. ## Workflow -Continuing the example in the previous section, here is a sample Grafana workflow. +Continuing the example in the previous section, here is a sample Grafana workflow. 1. Install Grafana. 1. Set up data sources. 1. Create panels. -1. Create dashboards. +1. Create dashboards. 1. Enter queries. 1. Add users. 1. Create playlists. ## Next steps -Concept tasks often link to related information, including *tasks* related to the concept and *reference* topics related to the concept. +Concept tasks often link to related information, including _tasks_ related to the concept and _reference_ topics related to the concept. diff --git a/contribute/templates/doc-reference-template.md b/contribute/templates/doc-reference-template.md index 642c735e1e7..2309b322dc4 100644 --- a/contribute/templates/doc-reference-template.md +++ b/contribute/templates/doc-reference-template.md @@ -15,9 +15,9 @@ weight = 100 # Reference -The *reference* topic type is for storing reference information, such as extensive tables, lists, or other information that is used as support for a task. Reference topics are also designed for API information. +The _reference_ topic type is for storing reference information, such as extensive tables, lists, or other information that is used as support for a task. Reference topics are also designed for API information. -Often reference topics are linked from *task* topics, because they contain information the user needs in order to perform a task. +Often reference topics are linked from _task_ topics, because they contain information the user needs in order to perform a task. [Grafana CLI](https://grafana.com/docs/grafana/latest/administration/cli/) is one example of a reference topic. @@ -41,12 +41,12 @@ The [Glossary](https://grafana.com/docs/grafana/latest/guides/glossary/) provide While you might not need a heading for each table, headings are a good way to chunk information if you have several tables. They also make the content easy to skim. Use headings or intro paragraphs like this one to explain to the reader what the information in the table is used for. -| | | | | | | -|:---|:---|:--:|:--:|---:|---:| -| | | | | | | -| | | | | | | -| | | | | | | -| | | | | | | +| | | | | | | +| :-- | :-- | :-: | :-: | --: | --: | +| | | | | | | +| | | | | | | +| | | | | | | +| | | | | | | ### Empty HTML table diff --git a/contribute/templates/doc-task-template.md b/contribute/templates/doc-task-template.md index 194ae011493..12daf739a3b 100644 --- a/contribute/templates/doc-task-template.md +++ b/contribute/templates/doc-task-template.md @@ -14,7 +14,7 @@ weight = 100 # Task -A *task* topic is intended for a procedure that describes how to accomplish a task. It lists a series of steps that users follow to produce an intended outcome. It tells the reader *how* to do something. [Install Grafana plugins](https://grafana.com/docs/grafana/latest/plugins/installation/) and [Playlist](https://grafana.com/docs/grafana/latest/reference/playlist/) are examples of task topics. Playlist includes a small amount of concept information in the introduction, which is appropriate. +A _task_ topic is intended for a procedure that describes how to accomplish a task. It lists a series of steps that users follow to produce an intended outcome. It tells the reader _how_ to do something. [Install Grafana plugins](https://grafana.com/docs/grafana/latest/plugins/installation/) and [Playlist](https://grafana.com/docs/grafana/latest/reference/playlist/) are examples of task topics. Playlist includes a small amount of concept information in the introduction, which is appropriate. Always include an introduction of a short paragraph or two to explain what the task is for, perhaps give the reader an idea of what the outcome will be. @@ -52,6 +52,6 @@ Thanks to internet search engines, every page in the documentation could be page ## Testing -It is a good practice to have someone else test the task you have written. If they can successfully complete the task using *only* what the steps you have written, not guessing or using their inherent knowledge, then your task has passed the test. However, it is very common to find you have skipped steps, because *you* are very familiar with Grafana and the topic you are explaining. +It is a good practice to have someone else test the task you have written. If they can successfully complete the task using _only_ what the steps you have written, not guessing or using their inherent knowledge, then your task has passed the test. However, it is very common to find you have skipped steps, because _you_ are very familiar with Grafana and the topic you are explaining. New users or people from other teams are very helpful for these tests. diff --git a/docs/sources/installation/docker.md b/docs/sources/installation/docker.md index 7b69d895a9f..6f33059df3f 100755 --- a/docs/sources/installation/docker.md +++ b/docs/sources/installation/docker.md @@ -24,7 +24,7 @@ You can run Grafana on your own hardware or use [Grafana Cloud](https://grafana. ## Alpine image (recommended) -**Grafana Enterprise edition**: `grafana/grafana-enterprise:` +**Grafana Enterprise edition**: `grafana/grafana-enterprise:` **Grafana Open Source edition**: `grafana/grafana-oss:` @@ -259,4 +259,3 @@ Refer to [Configure a Grafana Docker image]({{< relref "../administration/config ## Configure Grafana Refer to the [Configuration]({{< relref "../administration/configuration.md" >}}) page for details on options for customizing your environment, logging, database, and so on. - diff --git a/docs/sources/release-notes/release-notes-7-5-4.md b/docs/sources/release-notes/release-notes-7-5-4.md index 650c35b3919..5e90d364eae 100644 --- a/docs/sources/release-notes/release-notes-7-5-4.md +++ b/docs/sources/release-notes/release-notes-7-5-4.md @@ -21,4 +21,3 @@ list = false - **Datasource:** Prevent default data source named "default" from causing infinite loop. [#32949](https://github.com/grafana/grafana/pull/32949), [@jackw](https://github.com/jackw) - **Prometheus:** Allow exemplars endpoint in data source proxy. [#32802](https://github.com/grafana/grafana/pull/32802), [@zoltanbedi](https://github.com/zoltanbedi) - **Table:** Fix table data links so they refer to correct row after sorting. [#32571](https://github.com/grafana/grafana/pull/32571), [@torkelo](https://github.com/torkelo) - diff --git a/docs/sources/release-notes/release-notes-8-0-0-beta3.md b/docs/sources/release-notes/release-notes-8-0-0-beta3.md index 5fbf8936677..1a3a067eaa1 100644 --- a/docs/sources/release-notes/release-notes-8-0-0-beta3.md +++ b/docs/sources/release-notes/release-notes-8-0-0-beta3.md @@ -38,7 +38,7 @@ list = false - **Admin:** Fix infinite loading edit on the profile page. [#34627](https://github.com/grafana/grafana/pull/34627), [@hugohaggmark](https://github.com/hugohaggmark) - **Color:** Fix issues with random colors in string and date fields. [#34913](https://github.com/grafana/grafana/pull/34913), [@torkelo](https://github.com/torkelo) - **Dashboard:** Fix issue with title or folder change has no effect after exiting settings view. [#34677](https://github.com/grafana/grafana/pull/34677), [@torkelo](https://github.com/torkelo) -- **DataLinks:** Fix an issue __series.name is not working in data link. [#34932](https://github.com/grafana/grafana/pull/34932), [@torkelo](https://github.com/torkelo) +- **DataLinks:** Fix an issue \_\_series.name is not working in data link. [#34932](https://github.com/grafana/grafana/pull/34932), [@torkelo](https://github.com/torkelo) - **Datasource:** Fix dataproxy timeout should always be applied for outgoing data source HTTP requests. [#34597](https://github.com/grafana/grafana/pull/34597), [@dsotirakis](https://github.com/dsotirakis) - **Elasticsearch:** Fix NewClient not passing httpClientProvider to client impl. [#34539](https://github.com/grafana/grafana/pull/34539), [@KiVirgil](https://github.com/KiVirgil) - **Explore:** Fix Browser title not updated on Navigation to Explore. [#34651](https://github.com/grafana/grafana/pull/34651), [@axelavargas](https://github.com/axelavargas) @@ -53,8 +53,6 @@ list = false ### Breaking changes - -The default HTTP method for Prometheus data source is now POST. Previously, it was GET. The POST APIs have been available since January 2018 (Prometheus 2.1.0) and they have fewer limitations than the GET APIs. For example, when dealing with high cardinality labels, GET hits the URL size limit. +The default HTTP method for Prometheus data source is now POST. Previously, it was GET. The POST APIs have been available since January 2018 (Prometheus 2.1.0) and they have fewer limitations than the GET APIs. For example, when dealing with high cardinality labels, GET hits the URL size limit. If you have a Prometheus instance with version < 2.1.0, which uses the default HTTP method, update your HTTP method to GET. Issue [#34599](https://github.com/grafana/grafana/issues/34599) - diff --git a/docs/sources/release-notes/release-notes-8-1-0-beta1.md b/docs/sources/release-notes/release-notes-8-1-0-beta1.md index 4d5a7e3785c..d79ecdfee31 100644 --- a/docs/sources/release-notes/release-notes-8-1-0-beta1.md +++ b/docs/sources/release-notes/release-notes-8-1-0-beta1.md @@ -33,9 +33,9 @@ list = false - **InfluxDB:** InfluxQL: adds tags to timeseries data. [#36702](https://github.com/grafana/grafana/pull/36702), [@gabor](https://github.com/gabor) - **InfluxDB:** InfluxQL: make measurement search case insensitive. [#34563](https://github.com/grafana/grafana/pull/34563), [@gabor](https://github.com/gabor) - **Legacy Alerting:** Replace simplejson with a struct in webhook notification channel. [#34952](https://github.com/grafana/grafana/pull/34952), [@KEVISONG](https://github.com/KEVISONG) -- **Legend:** Updates display name for Last (not null) to just Last*. [#35633](https://github.com/grafana/grafana/pull/35633), [@torkelo](https://github.com/torkelo) +- **Legend:** Updates display name for Last (not null) to just Last\*. [#35633](https://github.com/grafana/grafana/pull/35633), [@torkelo](https://github.com/torkelo) - **Logs panel:** Add option to show common labels. [#36166](https://github.com/grafana/grafana/pull/36166), [@ivanahuckova](https://github.com/ivanahuckova) -- **Loki:** Add $__range variable. [#36175](https://github.com/grafana/grafana/pull/36175), [@ivanahuckova](https://github.com/ivanahuckova) +- **Loki:** Add $\_\_range variable. [#36175](https://github.com/grafana/grafana/pull/36175), [@ivanahuckova](https://github.com/ivanahuckova) - **Loki:** Add support for "label_values(log stream selector, label)" in templating. [#35488](https://github.com/grafana/grafana/pull/35488), [@ivanahuckova](https://github.com/ivanahuckova) - **Loki:** Add support for ad-hoc filtering in dashboard. [#36393](https://github.com/grafana/grafana/pull/36393), [@ivanahuckova](https://github.com/ivanahuckova) - **MySQL Datasource:** Add timezone parameter. [#27535](https://github.com/grafana/grafana/pull/27535), [@andipabst](https://github.com/andipabst) @@ -74,20 +74,17 @@ list = false ### Breaking changes - When parsing Elasticsearch query responses using template variables, each field gets named after the variable value instead of the name. For example, executing a `terms` aggregation on a variable named `$groupBy` that has `@hostname` as a value, the resulting column in the table response will be `@hostname` instead of `$groupBy` Issue [#36035](https://github.com/grafana/grafana/issues/36035) - Azure Monitor data source no longer supports different credentials for Metrics and Logs in existing data sources. To use different credentials for Azure Monitor Logs, create another data source. Issue [#35121](https://github.com/grafana/grafana/issues/35121) Existing Azure Metrics Logs queries for Log Analytics Workspaces should be backward compatible with this change and should not get impacted. Panels will be migrated to use the new resource-centric backend when you first edit and save them. Application Insights and Insights Analytics queries are now read-only and cannot be modified. To update Application Insights queries, users can manually recreate them as Metrics queries, and Insights Analytics are recreated with Logs. - Issue [#33879](https://github.com/grafana/grafana/issues/33879) +Issue [#33879](https://github.com/grafana/grafana/issues/33879) ### Plugin development fixes & changes - **Toolkit:** Improve error messages when tasks fail. [#36381](https://github.com/grafana/grafana/pull/36381), [@joshhunt](https://github.com/joshhunt) - diff --git a/docs/sources/release-notes/release-notes-8-1-0.md b/docs/sources/release-notes/release-notes-8-1-0.md index 635d64bc126..754fabc064e 100644 --- a/docs/sources/release-notes/release-notes-8-1-0.md +++ b/docs/sources/release-notes/release-notes-8-1-0.md @@ -13,7 +13,7 @@ list = false - **Alerting:** Deduplicate receivers during migration. [#36812](https://github.com/grafana/grafana/pull/36812), [@codesome](https://github.com/codesome) - **ColorPicker:** Display colors as RGBA. [#37231](https://github.com/grafana/grafana/pull/37231), [@nikki-kiga](https://github.com/nikki-kiga) - **Encryption:** Add support for multiple encryption algorithms (aes-gcm). (Enterprise) -- **Select:** Make portalling the menu opt-in, but opt-in *everywhere*. [#37501](https://github.com/grafana/grafana/pull/37501), [@ashharrison90](https://github.com/ashharrison90) +- **Select:** Make portalling the menu opt-in, but opt-in _everywhere_. [#37501](https://github.com/grafana/grafana/pull/37501), [@ashharrison90](https://github.com/ashharrison90) - **TeamSync:** Batch team synchronization. (Enterprise) - **TimeRangePicker:** Improve accessibility. [#36912](https://github.com/grafana/grafana/pull/36912), [@tskarhed](https://github.com/tskarhed) @@ -32,4 +32,3 @@ list = false - **PasswordField:** Prevent a password from being displayed when you click the Enter button. [#37444](https://github.com/grafana/grafana/pull/37444), [@tskarhed](https://github.com/tskarhed) - **Renderer:** Remove debug.log file when Grafana is stopped. [#37367](https://github.com/grafana/grafana/pull/37367), [@AgnesToulet](https://github.com/AgnesToulet) - **Security:** Update dependencies to fix CVE-2021-36222. [#37546](https://github.com/grafana/grafana/pull/37546), [@ying-jeanne](https://github.com/ying-jeanne) - diff --git a/docs/sources/release-notes/release-notes-8-1-1.md b/docs/sources/release-notes/release-notes-8-1-1.md index de01476d455..8c48a07a57b 100644 --- a/docs/sources/release-notes/release-notes-8-1-1.md +++ b/docs/sources/release-notes/release-notes-8-1-1.md @@ -12,4 +12,3 @@ list = false - **CloudWatch Logs:** Fix crash when no region is selected. [#37639](https://github.com/grafana/grafana/pull/37639), [@aocenas](https://github.com/aocenas) - **Reporting:** Fix timezone parsing for scheduler. (Enterprise) - diff --git a/docs/sources/release-notes/release-notes-8-2-0-beta1.md b/docs/sources/release-notes/release-notes-8-2-0-beta1.md index f16ecea55ad..626f4ff1c81 100644 --- a/docs/sources/release-notes/release-notes-8-2-0-beta1.md +++ b/docs/sources/release-notes/release-notes-8-2-0-beta1.md @@ -70,26 +70,22 @@ list = false ### Breaking changes - The `monaco-editor` dependency in `grafana-ui` has been updated to a newer version (`0.27.0`), which is not completely backward compatible with the old version (`0.21.2`). The backward incompatible changes are fairly small, but they do exist, so if your code accesses the raw monaco-objects through the `grafana-ui` package, please check the [monaco-editor changelog](https://github.com/microsoft/monaco-editor/blob/main/CHANGELOG.md) and apply any necessary changes. Issue [#39027](https://github.com/grafana/grafana/issues/39027) - -The mandatory `css` prop in `grafana/ui` components has been removed. +The mandatory `css` prop in `grafana/ui` components has been removed. Previous versions of `grafana/ui` components were typed incorrectly due to a dependency mismatch between emotion 10 and 11 causing a `css` prop to be added to components that extended react types. - Issue [#38078](https://github.com/grafana/grafana/issues/38078) +Issue [#38078](https://github.com/grafana/grafana/issues/38078) +### Unified Alerting (Grafana 8 Alerting) data loss -### Unified Alerting (Grafana 8 Alerting) data loss +Grafana v8.2 fixed an issue with org isolation for notification configuration but to fix this Grafana will now re-run the migration from old alerting and this will cause complete removal of all new alert rules and notification configurations. This data loss is not something we find acceptable and are working on ways to mitigate it. So in the meantime, if you are an early adopter of unified alerting please wait with trying v8.2 beta. +Issue [#37414](https://github.com/grafana/grafana/issues/37414) -Grafana v8.2 fixed an issue with org isolation for notification configuration but to fix this Grafana will now re-run the migration from old alerting and this will cause complete removal of all new alert rules and notification configurations. This data loss is not something we find acceptable and are working on ways to mitigate it. So in the meantime, if you are an early adopter of unified alerting please wait with trying v8.2 beta. - Issue [#37414](https://github.com/grafana/grafana/issues/37414) - -Panel queries and/or annotation queries that used more than one statistic will be converted into one query/annotation per statistic. In case an alerting rule was based on a query row that had more than one statistic, it would now be based only on the first statistic for that query row. New alerting rules will not be created for migrated queries. Please note that in most cases it would not make sense to have an alerting rule that is based on multiple statistics anyway. Issue [#36925](https://github.com/grafana/grafana/issues/36925) +Panel queries and/or annotation queries that used more than one statistic will be converted into one query/annotation per statistic. In case an alerting rule was based on a query row that had more than one statistic, it would now be based only on the first statistic for that query row. New alerting rules will not be created for migrated queries. Please note that in most cases it would not make sense to have an alerting rule that is based on multiple statistics anyway. Issue [#36925](https://github.com/grafana/grafana/issues/36925) ### Deprecations - `getHighlighterExpressions` in datasource APIs ( used to highlight logs while editing queries) has been deprecated and will be removed in a future release. # Deprecation notice @@ -99,4 +95,3 @@ Panel queries and/or annotation queries that used more than one statistic will b ### Plugin development fixes & changes - **Grafana UI:** Fix TS error property `css` is missing in type. [#38078](https://github.com/grafana/grafana/pull/38078), [@jackw](https://github.com/jackw) - diff --git a/package.json b/package.json index fe607778d2a..4f0298fe3ee 100644 --- a/package.json +++ b/package.json @@ -33,8 +33,8 @@ "packages:typecheck": "lerna run typecheck", "packages:clean": "lerna run clean", "precommit": "yarn run lint-staged", - "prettier:check": "prettier --list-different \"**/*.{ts,tsx,scss}\"", - "prettier:write": "prettier --list-different \"**/*.{ts,tsx,scss,js}\" --write", + "prettier:check": "prettier --list-different \"**/*.{ts,tsx,scss,md,mdx}\"", + "prettier:write": "prettier --list-different \"**/*.{ts,tsx,scss,js,md,mdx}\" --write", "prestart": "yarn themes:generate", "prestart:hot": "yarn themes:generate", "prestart:noTsCheck": "yarn themes:generate", diff --git a/packages/README.md b/packages/README.md index 1e0ee2c5dcc..8fe4b89b63e 100644 --- a/packages/README.md +++ b/packages/README.md @@ -3,25 +3,30 @@ This document contains information about Grafana frontend package versioning and releases. ## Versioning + We use [Lerna](https://github.com/lerna/lerna) for packages versioning and releases. All packages are versioned according to the current Grafana version: -- Grafana v6.3.0-alpha1 -> @grafana/* packages @ 6.3.0-alpha.1 -- Grafana v6.2.5 -> @grafana/* packages @ 6.2.5 -- Grafana - main branch version (based on package.json, i.e. 6.4.0-pre) -> @grafana/* packages @ 6.4.0-pre- (see details below about packages publishing channels) + +- Grafana v6.3.0-alpha1 -> @grafana/\* packages @ 6.3.0-alpha.1 +- Grafana v6.2.5 -> @grafana/\* packages @ 6.2.5 +- Grafana - main branch version (based on package.json, i.e. 6.4.0-pre) -> @grafana/\* packages @ 6.4.0-pre- (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. ### Stable releases + > **Even though packages are released under a stable version, they are considered ALPHA until further notice!** Stable releases are published under the `latest` tag on npm. If there was alpha/beta version released previously, the `next` tag is updated to stable version. ### Alpha and beta releases + Alpha and beta releases are published under the `next` tag on npm. ### Automatic prereleases -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: + +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: ``` - @@ -58,38 +63,41 @@ As mentioned above the `canary` releases are published to the Github package reg > Make sure you are logged in to npm in your terminal and that you are a part of Grafana org on npm. 1. Run `yarn packages:prepare` script from the root directory. This performs tests on the packages and prompts for the version of the packages. The version should be the same as the one being released. - - Make sure you use semver convention. So, *place a dot between prerelease id and prerelease number*, i.e. 6.3.0-alpha.1 + - Make sure you use semver convention. So, _place a dot between prerelease id and prerelease number_, i.e. 6.3.0-alpha.1 - Make sure you confirm the version bump when prompted! -2. Commit changes (lerna.json and package.json files) - *"Packages version update: \"* +2. Commit changes (lerna.json and package.json files) - _"Packages version update: \"_ 3. Run `yarn packages:build` script that prepares distribution packages in `packages/grafana-*/dist`. These directories are going to be published to npm. 4. Depending whether or not it's a prerelease: + - When releasing a prerelease run `packages:publishNext` to publish new versions. - When releasing a stable version run `packages:publishLatest` to publish new versions. 5. Push version commit to the release branch. ### Building individual packages + To build individual packages, run: ``` grafana-toolkit package:build --scope= ``` -### Setting up @grafana/* packages for local development +### Setting up @grafana/\* packages for local development -A known issue with @grafana/* packages is that a lot of times we discover problems on canary channel(see [versioning overview](#Versioning)) when the version was already pushed to npm. +A known issue with @grafana/\* packages is that a lot of times we discover problems on canary channel(see [versioning overview](#Versioning)) when the version was already pushed 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 main. +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. #### Setting up local npm registry -From your terminal: -1. Modify `/etc/hosts` file and add the following entry: ```127.0.0.1 grafana-npm.local``` -2. Navigate to `devenv/local-npm` directory. +From your terminal: + +1. Modify `/etc/hosts` file and add the following entry: `127.0.0.1 grafana-npm.local` +2. Navigate to `devenv/local-npm` directory. 3. Run `docker-compose up`. This will start your local npm registry, available at http://grafana-npm.local:4873/ -4. Run `npm login --registry=http://grafana-npm.local:4873 --scope=@grafana` . This will allow you to publish any @grafana/* package into the local registry. +4. Run `npm login --registry=http://grafana-npm.local:4873 --scope=@grafana` . This will allow you to publish any @grafana/\* package into the local registry. 5. Run `npm config set @grafana:registry http://grafana-npm.local:4873`. This will config your npm to install @grafana scoped packages from your local registry. #### Publishing packages to local npm registry @@ -97,13 +105,14 @@ From your terminal: You need to follow [manual packages release procedure](#manual-release). The only difference is you need to run `yarn packages:publishDev` task in order to publish to you local registry. From your terminal: + 1. Run `yarn packages:prepare`. 2. Commit changes in package.json and lerna.json files 3. Build packages: `yarn packages:build` -4. Run `yarn packages:publishDev`. +4. Run `yarn packages:publishDev`. 5. Navigate to http://grafana-npm.local:4873 and verify that version was published -Locally published packages will be published under `dev` channel, so in your plugin package.json file you can use that channel. For example: +Locally published packages will be published under `dev` channel, so in your plugin package.json file you can use that channel. For example: ``` // plugin's package.json diff --git a/packages/grafana-data/CHANGELOG.md b/packages/grafana-data/CHANGELOG.md index 556d4241a68..5459e379e0a 100644 --- a/packages/grafana-data/CHANGELOG.md +++ b/packages/grafana-data/CHANGELOG.md @@ -1,3 +1,3 @@ # (2019-07-08) -First public release +First public release diff --git a/packages/grafana-e2e-selectors/CHANGELOG.md b/packages/grafana-e2e-selectors/CHANGELOG.md index 139597f9cb0..e69de29bb2d 100644 --- a/packages/grafana-e2e-selectors/CHANGELOG.md +++ b/packages/grafana-e2e-selectors/CHANGELOG.md @@ -1,2 +0,0 @@ - - diff --git a/packages/grafana-e2e/CHANGELOG.md b/packages/grafana-e2e/CHANGELOG.md index 139597f9cb0..e69de29bb2d 100644 --- a/packages/grafana-e2e/CHANGELOG.md +++ b/packages/grafana-e2e/CHANGELOG.md @@ -1,2 +0,0 @@ - - diff --git a/packages/grafana-runtime/CHANGELOG.md b/packages/grafana-runtime/CHANGELOG.md index 556d4241a68..5459e379e0a 100644 --- a/packages/grafana-runtime/CHANGELOG.md +++ b/packages/grafana-runtime/CHANGELOG.md @@ -1,3 +1,3 @@ # (2019-07-08) -First public release +First public release diff --git a/packages/grafana-toolkit/CHANGELOG.md b/packages/grafana-toolkit/CHANGELOG.md index 35cb7751af8..aba77fd4854 100644 --- a/packages/grafana-toolkit/CHANGELOG.md +++ b/packages/grafana-toolkit/CHANGELOG.md @@ -1,16 +1,19 @@ # 7.3.0-beta1 (2020-10-15) ### Features / Enhancements -* **grafana/toolkit**: expose Jest maxWorkers arg for plugin test & build tasks. [#27724](https://github.com/grafana/grafana/pull/27724), [@domasx2](https://github.com/domasx2) + +- **grafana/toolkit**: expose Jest maxWorkers arg for plugin test & build tasks. [#27724](https://github.com/grafana/grafana/pull/27724), [@domasx2](https://github.com/domasx2) # 7.2.1 (2020-10-08) ### Features / Enhancements -* **grafana/toolkit**: Add --coverage flag to plugin build command. [#27743](https://github.com/grafana/grafana/pull/27743), [@gassiss](https://github.com/gassiss) + +- **grafana/toolkit**: Add --coverage flag to plugin build command. [#27743](https://github.com/grafana/grafana/pull/27743), [@gassiss](https://github.com/gassiss) # 7.2.0 (2020-09-23) ### Bug Fixes + - **grafana/toolkit**: avoid path.resolve with globby in moveStaticFiles. [#27670](https://github.com/grafana/grafana/pull/27670), [@kennytm](https://github.com/kennytm) # 7.0.0 (2020-05-18) @@ -22,11 +25,13 @@ # 7.0.0-beta.1 (2020-04-28) ### Features / Enhancements + - **Grafana Toolkit**: Adds template for backend data source. [#23864](https://github.com/grafana/grafana/pull/23864), [@bergquist](https://github.com/bergquist) # 6.6.0-beta1 (2020-01-20) ### Features / Enhancements + - **grafana/toolkit**: Add option to override webpack config. [#20872](https://github.com/grafana/grafana/pull/20872), [@sebimarkgraf](https://github.com/sebimarkgraf) # 6.4.0 (2019-10-01) @@ -34,7 +39,9 @@ # 6.4.0-beta2 (2019-09-25) ### Features / Enhancements + - **grafana/toolkit**: Add plugin creation task. [#19207](https://github.com/grafana/grafana/pull/19207), [@dprokop](https://github.com/dprokop) # 6.4.0-beta1 (2019-09-17) + First release, see [Readme](https://github.com/grafana/grafana/blob/v6.4.0-beta1/packages/grafana-toolkit/README.md) for details. diff --git a/packages/grafana-toolkit/docker/grafana-plugin-ci-alpine/README.md b/packages/grafana-toolkit/docker/grafana-plugin-ci-alpine/README.md index bb852b616de..94b42aefd3d 100644 --- a/packages/grafana-toolkit/docker/grafana-plugin-ci-alpine/README.md +++ b/packages/grafana-toolkit/docker/grafana-plugin-ci-alpine/README.md @@ -2,18 +2,21 @@ Uploaded to dockerhub as grafana/grafana-plugin-ci:latest-alpine -Based off of `circleci/node:12-browsers` +Based off of `circleci/node:12-browsers` ## User + The user will be `circleci` The home directory will be `/home/circleci` ## Node + - node 12 is installed - yarn is installed globally - npm is installed globally ## Go + - Go is installed in `/usr/local/bin/go` - golangci-lint is installed in `/usr/local/bin/golangci-lint` - mage is installed in `/home/circleci/go/bin/mage` @@ -21,17 +24,21 @@ The home directory will be `/home/circleci` All of the above directories are in the path, so there is no need to specify fully qualified paths. ## Grafana + - Installed in `/home/circleci/src/grafana` - `yarn install` has been run ## Integration/Release Testing + There are 4 previous versions pre-downloaded to /usr/local/grafana. These versions are: + 1. 6.6.2 2. 6.5.3 3. 6.4.5 4. 6.3.7 To test, your CircleCI config will need a run section with something similar to the following + ``` - run: name: Setup Grafana (local install) @@ -43,15 +50,18 @@ To test, your CircleCI config will need a run section with something similar to grafana-cli --version ``` - # Building + To build, cd to `/packages/grafana-toolkit/docker/grafana-plugin-ci-alpine` + ``` ./build.sh ``` # Developing/Testing + To test, you should have docker-compose installed. + ``` cd test ./start.sh diff --git a/packages/grafana-toolkit/docker/grafana-plugin-ci/README.md b/packages/grafana-toolkit/docker/grafana-plugin-ci/README.md index 51f67cf4062..18bc1aec592 100644 --- a/packages/grafana-toolkit/docker/grafana-plugin-ci/README.md +++ b/packages/grafana-toolkit/docker/grafana-plugin-ci/README.md @@ -1,19 +1,22 @@ # Using this docker image -Currently tagged and uploaded to dockerhub as srclosson/integrations-ci-build +Currently tagged and uploaded to dockerhub as srclosson/integrations-ci-build -Based off of `circleci/node:12-browsers` +Based off of `circleci/node:12-browsers` ## User + The user will be `circleci` The home directory will be `/home/circleci` ## Node + - node 12 is installed - yarn is installed globally - npm is installed globally ## Go + - Go is installed in `/usr/local/bin/go` - golangci-lint is installed in `/usr/local/bin/golangci-lint` - mage is installed in `/home/circleci/go/bin/mage` @@ -21,17 +24,21 @@ The home directory will be `/home/circleci` All of the above directories are in the path, so there is no need to specify fully qualified paths. ## Grafana + - Installed in `/home/circleci/src/grafana` - `yarn install` has been run ## Integration/Release Testing + There are 4 previous versions pre-downloaded to /usr/local/grafana. These versions are: + 1. 6.6.2 2. 6.5.3 3. 6.4.5 4. 6.3.7 To test, your CircleCI config will need a run section with something similar to the following + ``` - run: name: Setup Grafana (local install) @@ -43,15 +50,18 @@ To test, your CircleCI config will need a run section with something similar to grafana-cli --version ``` - # Building + To build, cd to `/packages/grafana-toolkit/docker/grafana-plugin-ci` + ``` ./build.sh ``` # Developing/Testing + To test, you should have docker-compose installed. + ``` cd test ./start.sh diff --git a/packages/grafana-ui/CHANGELOG.md b/packages/grafana-ui/CHANGELOG.md index f894f1dd719..efef3a4a8ef 100644 --- a/packages/grafana-ui/CHANGELOG.md +++ b/packages/grafana-ui/CHANGELOG.md @@ -1,23 +1,26 @@ # 7.3.0-beta1 (2020-10-15) ### Features / Enhancements -* **NamedColors**: Named colors refactors. [#28235](https://github.com/grafana/grafana/pull/28235), [@torkelo](https://github.com/torkelo) + +- **NamedColors**: Named colors refactors. [#28235](https://github.com/grafana/grafana/pull/28235), [@torkelo](https://github.com/torkelo) # 7.2.0 (2020-09-23) ### Features / Enhancements + - **grafana/ui**: Do not bundle jQuery. [#27667](https://github.com/grafana/grafana/pull/27667), [@kennytm](https://github.com/kennytm) # 7.1.0-beta1 (2020-07-01) ### Features / Enhancements + - **Grafana-UI**: Add FileUpload. [#25835](https://github.com/grafana/grafana/pull/25835), [@Clarity-89](https://github.com/Clarity-89) - **Switch**: Deprecate checked prop in favor of value. [#25862](https://github.com/grafana/grafana/pull/25862), [@tskarhed](https://github.com/tskarhed) - # 7.0.4 (2020-06-25) ### Features / Enhancements + - **Slider**: Update rc-slider dependency to 9.3.1. [#25617](https://github.com/grafana/grafana/pull/25617), [@torkelo](https://github.com/torkelo) # 7.0.0 (2020-05-18) diff --git a/packages/grafana-ui/src/Intro.story.mdx b/packages/grafana-ui/src/Intro.story.mdx index a4aa4b04d0b..11411323643 100644 --- a/packages/grafana-ui/src/Intro.story.mdx +++ b/packages/grafana-ui/src/Intro.story.mdx @@ -9,16 +9,20 @@ import { Meta } from '@storybook/addon-docs/blocks'; With the design system @grafana/ui, we want to democratize development. This library of reusable [Grafana](https://github.com/grafana/grafana) components and guidelines helps you with contribution and plugin development. ## 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: + - 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. - A beautiful, visually consistent Grafana experience. - Transparency about how we work and what we do. ### Maintained by Grafana Labs and you + 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 + 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 diff --git a/packages/grafana-ui/src/components/Alert/Alert.mdx b/packages/grafana-ui/src/components/Alert/Alert.mdx index 9f8ecba65a8..eee11214278 100644 --- a/packages/grafana-ui/src/components/Alert/Alert.mdx +++ b/packages/grafana-ui/src/components/Alert/Alert.mdx @@ -11,7 +11,7 @@ An alert displays an important message in a way that attracts the user's attenti # Usage ```jsx - + ``` - + diff --git a/packages/grafana-ui/src/components/BarGauge/BarGauge.mdx b/packages/grafana-ui/src/components/BarGauge/BarGauge.mdx index cefcce56ee9..e28cf46c99f 100644 --- a/packages/grafana-ui/src/components/BarGauge/BarGauge.mdx +++ b/packages/grafana-ui/src/components/BarGauge/BarGauge.mdx @@ -6,26 +6,27 @@ import { BarGauge } from './BarGauge'; # BarGauge ## Usage + ```tsx import { BarGauge, BarGaugeDisplayMode } from '@grafana/ui'; import { VizOrientation, ThresholdsMode, Field, FieldType, getDisplayProcessor } from '@grafana/data'; const field: Partial = { - type: FieldType.number, - config: { - min: minValue, - max: maxValue, - thresholds: { - mode: ThresholdsMode.Absolute, - steps: [ - { value: -Infinity, color: 'green' }, - { value: threshold1Value, color: threshold1Color }, - { value: threshold2Value, color: threshold2Color }, - ], - }, + type: FieldType.number, + config: { + min: minValue, + max: maxValue, + thresholds: { + mode: ThresholdsMode.Absolute, + steps: [ + { value: -Infinity, color: 'green' }, + { value: threshold1Value, color: threshold1Color }, + { value: threshold2Value, color: threshold2Color }, + ], }, - }; - field.display = getDisplayProcessor({ field }); + }, +}; +field.display = getDisplayProcessor({ field }); const value = { text: value.toString(), @@ -34,7 +35,14 @@ const value = { }; //... - +; ``` diff --git a/packages/grafana-ui/src/components/BigValue/BigValue.mdx b/packages/grafana-ui/src/components/BigValue/BigValue.mdx index 46ad7bf86b9..673b4e7b649 100644 --- a/packages/grafana-ui/src/components/BigValue/BigValue.mdx +++ b/packages/grafana-ui/src/components/BigValue/BigValue.mdx @@ -4,35 +4,40 @@ import { BigValue } from './BigValue'; # BigValue + Component for showing a value based on a [DisplayValue](https://grafana.com/docs/grafana/latest/packages_api/data/displayvalue/#displayvalue-interface). ### Display properties + There are a few properties that will determine the look of the BigValue. #### Justify mode + There are two modes for aligning text, auto and center. #### Graph mode + You can control graph shown in BigValue with the `GraphMode` property. `GraphMode.Area` renders a graph in the behind the value. `GrapMode.None` will hide it. #### Color mode + `ColorMode` controls which part of the component that should have the color from thresholds or field config, `ColorMode.Background` and `ColorMode.Value`. Note, `ColorMode.Value` will only set the color for the value. #### Text mode + There are four variants to render text: - * `TextMode.Auto` - Show value and name if there's more than on BigValue in the same pane. - * `TextMode.Value` - Show only the value. - * `TextMode.ValueAndName` - Show value and the name. - * `TextMode.None` - Do not show any value or name. - - +- `TextMode.Auto` - Show value and name if there's more than on BigValue in the same pane. +- `TextMode.Value` - Show only the value. +- `TextMode.ValueAndName` - Show value and the name. +- `TextMode.None` - Do not show any value or name. ### Example usage + An example usage is in the [Stat panel](https://grafana.com/docs/grafana/latest/panels/visualizations/stat-panel/). ```tsx @@ -43,14 +48,14 @@ import { BigValueGraphMode, BigValueJustifyMode, BigValueTextMode, - useTheme + useTheme, } from '@grafana/ui'; const bigValue: DisplayValue = { color: 'red', value: '5000', numeric: 5000, - title: 'Volume' + title: 'Volume', }; return ( @@ -63,8 +68,8 @@ return ( value={bigValue} /> ); - - ``` + ### Props + diff --git a/packages/grafana-ui/src/components/Card/Card.mdx b/packages/grafana-ui/src/components/Card/Card.mdx index 4594e8e1529..083f99519bb 100644 --- a/packages/grafana-ui/src/components/Card/Card.mdx +++ b/packages/grafana-ui/src/components/Card/Card.mdx @@ -1,49 +1,42 @@ -import { Meta, Preview, Props } from "@storybook/addon-docs/blocks"; -import { Card } from "./Card"; +import { Meta, Preview, Props } from '@storybook/addon-docs/blocks'; +import { Card } from './Card'; import { Button } from '../Button'; import { IconButton } from '../IconButton/IconButton'; -import {TagList} from '../Tags/TagList'; +import { TagList } from '../Tags/TagList'; -export const logo = 'https://grafana.com/static/assets/img/apple-touch-icon.png' +export const logo = 'https://grafana.com/static/assets/img/apple-touch-icon.png'; - + # Card ## Usage ### Basic + A basic `Card` component expects at least a heading, used as a title. + ```jsx - + ``` + - + - ### Multiple metadata elements + For providing metadata elements, which can be any extra information for the card, `Card.Meta` component should be used. If metadata consists of multiple strings, each of them has to be escaped (wrapped in brackets `{}`) or better passed in as an array. ```jsx - - {['Folder: Test', 'Views: 100']} - + {['Folder: Test', 'Views: 100']} ``` - - {['Folder: Test', 'Views: 100']} - + {['Folder: Test', 'Views: 100']} @@ -51,10 +44,12 @@ Metadata also accepts HTML elements, which could be links, for example. For elem ```jsx - + Grafana - https://ops-us-east4.grafana.net/api/prom - + + https://ops-us-east4.grafana.net/api/prom + + ``` @@ -62,7 +57,9 @@ Metadata also accepts HTML elements, which could be links, for example. For elem Grafana - https://ops-us-east4.grafana.net/api/prom + + https://ops-us-east4.grafana.net/api/prom + @@ -71,10 +68,12 @@ The separator for multiple metadata elements defaults to a vertical line `|`, bu ```jsx - + Grafana - https://ops-us-east4.grafana.net/api/prom - + + https://ops-us-east4.grafana.net/api/prom + + ``` @@ -82,32 +81,29 @@ The separator for multiple metadata elements defaults to a vertical line `|`, bu Grafana - https://ops-us-east4.grafana.net/api/prom + + https://ops-us-east4.grafana.net/api/prom + ### Tags + Tags can be rendered inside the Card, by being wrapped in `Card.Tags` component. Note that this component does not provide any tag styling and that should be handled by the children. It is recommended to use it with Grafana-UI's `TagList` component. ```jsx - + - console.log(tag)} /> + console.log(tag)} /> ``` - + - console.log(tag)} /> + console.log(tag)} /> @@ -120,73 +116,52 @@ Card can be used as a clickable link item by specifying `href` prop. In this cas ``` + ### Inside a list item To render cards in a list, it is possible to nest them inside `li` items. + ```jsx
  • - +
  • - +
  • - +
  • - +
``` + -