mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Edit of data requests and breaking changes docs (part 4 of Contribute doc quality project) (#88858)
* Docs: data requests and breaking changes edit * Update contribute/architecture/frontend-data-requests.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Fixes from review * Update contribute/architecture/frontend-data-requests.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update contribute/architecture/frontend-data-requests.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update contribute/breaking-changes-guide/breaking-changes-guide.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Fix from review * Update contribute/breaking-changes-guide/breaking-changes-guide.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Update contribute/breaking-changes-guide/breaking-changes-guide.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Fix from review * Update contribute/breaking-changes-guide/breaking-changes-guide.md Co-authored-by: Beverly Buchanan <131809838+BeverlyJaneJ@users.noreply.github.com> * Fixes from review * Update contribute/breaking-changes-guide/breaking-changes-guide.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * Fix from review * Fix from review * Fix alt text * Remove 1st person * Fix from review * Eliminate 'in case' --------- Co-authored-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Beverly Buchanan <131809838+BeverlyJaneJ@users.noreply.github.com>
This commit is contained in:
Joseph Perez
GitHub
parent
465efbf802
commit
f09f21b5bb
@ -1,9 +1,6 @@
|
||||
# Architecture
|
||||
|
||||
Are you looking to take on contributions with bigger impact? These guides help you get a better understanding of the structure and design of the Grafana codebase.
|
||||
Do you want to make Grafana contributions with bigger impact? These guides help you get a better understanding of the structure and design of the Grafana codebase.
|
||||
|
||||
Learn more about the backend architecture in [contribute/backend](/contribute/backend/README.md).
|
||||
|
||||
Learn more about the frontend architecture:
|
||||
|
||||
- Part 1: [Data requests](frontend-data-requests.md)
|
||||
- To learn more about the frontend architecture, refer to [Frontend data requests](frontend-data-requests.md).
|
||||
- To learn more about the backend architecture, refer to [contribute/backend](/contribute/backend/README.md).
|
||||
|
||||
@ -1,16 +1,18 @@
|
||||
# Data requests
|
||||
# Frontend data requests
|
||||
|
||||
[BackendSrv](https://github.com/grafana/grafana/blob/main/packages/grafana-runtime/src/services/backendSrv.ts) handles all outgoing HTTP requests from Grafana. This document explains the high-level concepts used by `BackendSrv`.
|
||||
|
||||
## Canceling requests
|
||||
## Cancel 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.
|
||||
While data sources can implement their own cancellation concept, we recommend that you use the method described in this section.
|
||||
|
||||
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.
|
||||
|
||||
If we wait for canceled requests to complete, it might create unnecessary load on data sources.
|
||||
If we wait for canceled requests to complete, they might create unnecessary load on the data sources.
|
||||
|
||||
Grafana uses a concept called _request cancellation_ to cancel any ongoing request that Grafana doesn't need.
|
||||
### Request cancellation by Grafana version
|
||||
|
||||
Grafana uses a concept called _request cancellation_ to cancel any ongoing request that Grafana doesn't need. The process for canceling requests in this manner varies by Grafana version.
|
||||
|
||||
#### Before Grafana 7.2
|
||||
|
||||
@ -25,22 +27,22 @@ The cancellation logic is as follows:
|
||||
|
||||
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://github.com/grafana/grafana/blob/main/packages/grafana-runtime/src/services/backendSrv.ts).
|
||||
|
||||
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)
|
||||
Migrating the core data sources to the new `fetch` function is an ongoing process. To learn more, refer to [this issue](https://github.com/grafana/grafana/issues/27222).
|
||||
|
||||
## Request queue
|
||||
|
||||
If Grafana isn't configured to support HTTP/2, browsers connecting with HTTP 1.1 enforce a limit of 4 - 8 parallel requests (the specific limit varies). Because of this limit, if some requests take a long time, they will block later requests and make interacting with Grafana very slow.
|
||||
If Grafana isn't configured to support HTTP/2, browsers connecting with HTTP 1.1 enforce a limit of 4 to 8 parallel requests (the specific limit varies). Because of this limit, if some requests take a long time, they will block later requests and make interacting with Grafana very slow.
|
||||
|
||||
[Enabling HTTP/2 support in Grafana](https://grafana.com/docs/grafana/latest/administration/configuration/#protocol) allows far more parallel requests.
|
||||
|
||||
#### Before Grafana 7.2
|
||||
### Before Grafana 7.2
|
||||
|
||||
Not supported.
|
||||
|
||||
#### After Grafana 7.2
|
||||
### 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.
|
||||
|
||||
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.
|
||||
Since the first implementation of the request queue doesn't take into account what browser the user uses, the request queue's limit for parallel data source requests is hard-coded to 5.
|
||||
|
||||
> **Note:** Grafana instances [configured with HTTP2](https://grafana.com/docs/grafana/latest/administration/configuration/#protocol) will have a hard coded limit of 1000.
|
||||
> **Note:** Grafana instances [configured with HTTP/2](https://grafana.com/docs/grafana/latest/administration/configuration/#protocol) have a hard-coded limit of 1000.
|
||||
|
||||
@ -1,81 +1,80 @@
|
||||
# Handling breaking changes in Grafana frontend APIs
|
||||
# Handle breaking changes in Grafana frontend APIs
|
||||
|
||||
This guide tries to help you identify and communicate breaking changes introduced to our frontend API.
|
||||
Follow this guide to identify and communicate breaking changes introduced to our frontend API.
|
||||
|
||||
- [What are our public APIs?](#what-are-our-public-apis)
|
||||
- [What is Levitate?](#what-is-levitate)
|
||||
- [How does the CI workflow look like?](#how-does-the-ci-workflow-look-like)
|
||||
- [I received a comment on my PR, what does it mean?](#i-received-a-comment-on-my-pr-what-does-it-mean)
|
||||
- [**I know it's a breaking change, what's next?**](#i-know-its-a-breaking-change-whats-next)
|
||||
- [What does the CI workflow look like?](#what-does-the-ci-workflow-look-like)
|
||||
- [What do comments on my PR mean?](#what-do-comments-on-my-pr-mean)
|
||||
- [I know it's a breaking change, what's next?](#i-know-its-a-breaking-change-whats-next)
|
||||
- [Introduce breaking changes only in major versions](#introduce-breaking-changes-only-in-major-versions)
|
||||
- [Deprecate first](#deprecate-first)
|
||||
- [Communicate](#communicate)
|
||||
- [I still have questions, who can help me out?](#i-still-have-questions-who-can-help-me-out)
|
||||
- [Who can help with other questions?](#who-can-help-with-other-questions)
|
||||
|
||||
---
|
||||
|
||||
## What are our public APIs?
|
||||
|
||||
The Grafana frontend codebase is exposing functionality through NPM packages to make plugin development easier and faster.
|
||||
The Grafana frontend codebase exposes functionality through NPM packages to make plugin development easier and faster.
|
||||
These packages live in the `/packages` folder and contain packages like:
|
||||
|
||||
- `@grafana/data`
|
||||
- `@grafana/runtime`
|
||||
- `@grafana/ui`
|
||||
- etc. ([They can be viewed here](https://github.com/grafana/grafana/tree/main/packages)
|
||||
- [(more packages...)](https://github.com/grafana/grafana/tree/main/packages)
|
||||
|
||||
Any change that causes dependent software to behave differently is considered to be breaking.
|
||||
|
||||
## What is Levitate?
|
||||
|
||||
[`@grafana/levitate`](https://github.com/grafana/levitate) is a tool created by Grafana that can show breaking changes between two versions of a **TypeScript** package or a source file.
|
||||
[`@grafana/levitate`](https://github.com/grafana/levitate) is a tool created by Grafana that can show breaking changes between two versions of a TypeScript package or a source file.
|
||||
|
||||
It can list exported members of an NPM package or imports used by an NPM package,
|
||||
**but we are mainly using it for comparing different versions of the same package to see changes in the exported members.**
|
||||
Levitate can list exported members of an NPM package or imports used by an NPM package, _but it is most commonly used for comparing different versions of the same package to see changes in the exported members._
|
||||
|
||||
A Github workflow runs against every pull request and comments a hint in case there are
|
||||
possible breaking changes. It also adds the `"breaking change"` label to the pull request.
|
||||
A GitHub workflow runs against every pull request and comments a hint if there are possible breaking changes.
|
||||
It also adds the `breaking change` label to the pull request.
|
||||
|
||||
## How does the CI workflow look like?
|
||||
## What does the CI workflow look like?
|
||||
|
||||
<img src="./breaking-changes-workflow.png" alt="CI workflow" width="700" />
|
||||
|
||||
## I received a comment on my PR, what does it mean?
|
||||
## What do comments on my PR mean?
|
||||
|
||||
|
||||
|
||||
|
||||
Receiving a comment like the one above does not necessarily mean that you actually introduced breaking
|
||||
changes (as certain edge cases are still not covered by the tool), but as there is a good chance we rather raise attention.
|
||||
Receiving a comment like this does not necessarily mean that you actually introduced breaking
|
||||
changes. This is because certain edge cases are still not covered by the tool, but there is a good chance that they may happen, so we call it to your attention.
|
||||
|
||||
By clicking the links in the comment ("more info" or "Check console output") you can view more detailed information about what triggered the notification.
|
||||
|
||||
**Removed exported members** (console view):<br />
|
||||
This means that some previously exported members won't be available in the newer version of the package which can break dependent plugins.
|
||||
This means that some previously exported members won't be available in the newer version of the package, so dependent plugins can break.
|
||||
|
||||
|
||||
|
||||
|
||||
**Changed an existing member** (console view):<br />
|
||||
This means that a member was changed in a way that can break dependent plugins.
|
||||
|
||||
|
||||
|
||||
|
||||
**No breaking changes** (console view):<br />
|
||||
Seeing this suggests that whilst changes were made, most probably none of them were breaking. You are good to go! 👏
|
||||
Seeing this suggests that while changes were made, most probably none of them were breaking. You are good to go! 👏
|
||||
|
||||
|
||||
|
||||
|
||||
## How can I decide if it is really a breaking change?
|
||||
|
||||
First go to the console output of the workflow and make sure that the diffs make sense.
|
||||
First, go to the console output of the workflow and make sure that the diffs make sense.
|
||||
|
||||
It can happen that Levitate highlights a change which is marked with TSDoc tags `// @alpha` or `// @internal` in
|
||||
which case you can choose to ignore it - keep in mind though that these flags won't really hold developers back
|
||||
It can happen that Levitate highlights a change which is marked with TSDoc tags `// @alpha` or `// @internal`, in
|
||||
which case you can choose to ignore it. Keep in mind though that these flags won't really hold developers back
|
||||
from using your code and most likely it is going to cause them problems if we are breaking them.
|
||||
|
||||
It can also happen that Levitate marks changing an interface as a possible breaking change.
|
||||
For anyone that implements that interface introducing a new property will break their code. Whilst this is correctly marked as a breaking change maybe it is an interface that is never implemented by other developers. In which case you can choose to ignore Levitate's message.
|
||||
Introducing a new property will break the code of anyone who implements that interface. While this is correctly marked as a breaking change maybe it is an interface that is never implemented by other developers. If this is the case, then you can choose to ignore Levitate's message.
|
||||
|
||||
These notifications are only warnings though, and **in the end it's up to the author of the PR to make a decision that makes the most sense.**
|
||||
These notifications are only warnings though, and _in the end it's up to the author of the PR to make a decision that makes the most sense._
|
||||
|
||||
## I know it's a breaking change, what's next?
|
||||
|
||||
@ -99,20 +98,20 @@ myOldFunction(name: string) {
|
||||
}
|
||||
```
|
||||
|
||||
1. Add a deprecation comment `// @deprecated`
|
||||
2. Add info in the comment about **when it is going to be removed**
|
||||
3. Add info in the comment about **what should be used instead**
|
||||
4. In case it's a function or a method, use `deprecationWarning(<file name>, <old name>, <new name>)` to raise attention during runtime as well
|
||||
5. Update the [migration guide](/developers/plugin-tools/migration-guides/) with your instructions
|
||||
1. Add a deprecation comment `// @deprecated`.
|
||||
2. Add info in the comment about _when it is going to be removed_.
|
||||
3. Add info in the comment about _what should be used instead_.
|
||||
4. If it's a function or a method, use `deprecationWarning(<FILENAME>, <OLD NAME>, <NEW NAME>)` to raise attention during runtime.
|
||||
5. Update the [migration guide](https://grafana.com/developers/plugin-tools/migration-guides/) with your instructions.
|
||||
|
||||
### Communicate
|
||||
|
||||
Reach out to **@grafana/plugins-platform-frontend** to help finding which plugins are using the code that is just about to change, so we try making it smoother by communicating it to them.
|
||||
Reach out to `@grafana/plugins-platform-frontend` to help find which plugins are using the code that is just about to change, so we try making it smoother by communicating it to the developers.
|
||||
|
||||
---
|
||||
|
||||
## I still have questions, who can help me out?
|
||||
## Who can help with other questions?
|
||||
|
||||
We are here to help.
|
||||
|
||||
Please either ping us in the pull request by using the **@grafana/plugins-platform-frontend** handle or reach out to us on the internal Slack in `#grafana-plugins-platform`.
|
||||
Please either ping us in the pull request by using the `@grafana/plugins-platform-frontend` handle or reach out to us on the internal Slack in `#grafana-plugins-platform`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user