IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2024-12-25 08:21:46 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Edit of "Developer Guide" and other topics (part 2 of doc quality project) (#86072)

Browse Source 
* Edit deprecation-policy

* Edit drone-pipeline

* Docs: Edit of 4 files, part 2 of quality improvement

* Update contribute/developer-guide.md

* Update contribute/developer-guide.md

Co-authored-by: J Stickler <julie.stickler@grafana.com>

* Changes from feedback

* Properly style UNIX

* Update contribute/drone-pipeline.md

* Update contribute/feature-toggles.md

Co-authored-by: J Stickler <julie.stickler@grafana.com>

* Format with prettier

---------

Co-authored-by: J Stickler <julie.stickler@grafana.com>
This commit is contained in:
Joseph Perez 2024-05-29 11:08:41 -07:00 committed by GitHub
parent e81f48ef95
commit 4e99cd2860
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 75 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
contribute/deprecation-policy.md
View File

@ -1,30 +1,32 @@
# Deprecation policy
We do our best to limit breaking changes and the deprecation of features to major releases. We always do our best **not** to introduce breaking changes in order to make upgrading Grafana as easy and reliable as possible. However, at times we have to introduce a breaking change by changing behavior or by removing a feature.
We do our best to limit breaking changes and the deprecation of features to major releases. We always do our best _not_ to introduce breaking changes in order to make upgrading Grafana as easy and reliable as possible. However, at times we have to introduce a breaking change by changing behavior or by removing a feature.
To minimize the negative effects of removing a feature we require a deprecation plan that includes:
To minimize the negative effects of removing a feature, we require a deprecation plan. A typical deprecation plan includes these features:
- Determine usage levels of the feature.
- Find alternative solutions and possible migration paths.
- Announce deprecation of the feature.
- Migrate users if possible
- Migrate users if possible.
- Give users time to adjust to the deprecation.
- Disable the feature by default.
- Remove the feature from the code base.
Depending on the size and importance of the feature this can be a design doc or an issue. We want this to be written communication for all parties so we know it's intentional and that did a reasonable attempt to avoid breaking changes unless needed. The size of the feature also means different notice times between Depreciation and disabling as well as disabling and removal. The actual duration will depend on releases of Grafana and the table below should be used as a guide.
We want the deprecation plan to be in the form of written communication for all parties so we know it's intentional and that a reasonable attempt was made to avoid breaking changes unnecessarily. Depending on the size and importance of the feature the plan can be a design doc or an issue.
Grafana employees can find more details in our internal docs.
> Grafana employees can find more details in our internal docs.
Additionally, the size of the feature requires different notice times between depreciation and disabling as well as disabling and removal. The actual duration will depend on releases of Grafana and the table below should be used as a guide.
## Grace period between announcement and disabling feature by default
| Size | Duration | Example |
| ------ | ---------- | ---------------------------------------------------------------- |
| Large | 1-2 years | Classic alerting, scripted dashboards, AngularJS |
| Medium | 6 months | Supported Database for Grafana's backend |
| Medium | 6 months | Supported database for Grafana's backend |
| Small | 1-3 months | Refresh OAuth access_token automatically using the refresh_token |
## Announced deprecations.
## Announced deprecations
| Name | Announcement Date | Disabling date | Removal Date | Description | Status |
| ------------------------------------------------------------------------ | ----------------- | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- | ------- |

119
contribute/developer-guide.md
View File

@ -8,8 +8,8 @@ Make sure you have the following dependencies installed before setting up your d
- [Git](https://git-scm.com/)
- [Go](https://golang.org/dl/) (see [go.mod](../go.mod#L3) for minimum required version)
- [Node.js (Long Term Support)](https://nodejs.org), with [corepack enabled](https://nodejs.org/api/corepack.html#enabling-the-feature). See [.nvmrc](../.nvmrc) for supported version. It's recommend you use a version manager such as [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm), or similar.
- GCC (required for Cgo dependencies)
- [Node.js (Long Term Support)](https://nodejs.org), with [corepack enabled](https://nodejs.org/api/corepack.html#enabling-the-feature). See [.nvmrc](../.nvmrc) for supported version. We recommend that you use a version manager such as [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm), or similar.
- [GCC](https://gcc.gnu.org/) (required for Cgo] dependencies)
### macOS
@ -33,88 +33,64 @@ We recommend using the Git command-line interface to download the source code fo
1. Open a terminal and run `git clone https://github.com/grafana/grafana.git`. This command downloads Grafana to a new `grafana` directory in your current directory.
1. Open the `grafana` directory in your favorite code editor.
For alternative ways of cloning the Grafana repository, please refer to [GitHub's cloning a repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) documentation.
For alternative ways of cloning the Grafana repository, refer to [GitHub's documentation](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository).
**Warning:** Do not use `go get` to download Grafana. Recent versions of Go have added behavior which isn't compatible with the way the Grafana repository is structured.
> **Caution:** Do not use `go get` to download Grafana. Recent versions of Go have added behavior which isn't compatible with the way the Grafana repository is structured.
### Configure precommit hooks
We use pre-commit hooks (via [lefthook](https://github.com/evilmartians/lefthook)) to lint, fix, and format code as you commit your changes. Previously the Grafana repository automatically installed these hook when you did `yarn install`, but they are now opt in for all contributors
We use pre-commit hooks (via [lefthook](https://github.com/evilmartians/lefthook)) to lint, fix, and format code as you commit your changes. Previously, the Grafana repository automatically installed these hook when you ran `yarn install`, but they are now opt-in for all contributors.
Install the lefthook precommit hooks with:
To install the precommit hooks:
```sh
make lefthook-install
```
To remove precommit hooks, run
To remove precommit hooks:
```sh
make lefthook-uninstall
```
> [!NOTE]
> Contributors working on the frontend are highly encouraged to install the precommit hooks, even if your IDE formats on save, so the `.betterer.results` file is kept up to sync.
> We strongly encourage contributors who work on the frontend to install the precommit hooks, even if your IDE formats on save. By doing so, the `.betterer.results` file is kept in sync.
## Build Grafana
Grafana consists of two components; the _frontend_, and the _backend_.
When building Grafana, be aware that it consists of two components:
- The _frontend_, and
- The _backend_.
### Frontend
Before we can build the frontend assets, we need to install the dependencies:
Before you can build the frontend assets, you need to install the related dependencies:
```
yarn install --immutable
```
> Troubleshooting: if you get the error `The remote archive doesn't match the expected checksum` for a dependency pulled from a link (e.g. `"tether-drop": "https://github.com/torkelo/drop"`): this is a temporary mismatch. To work around it (while someone corrects the issue), you can prefix your `yarn install --immutable` command with [`YARN_CHECKSUM_BEHAVIOR=update`](https://yarnpkg.com/advanced/error-codes#yn0018---cache_checksum_mismatch)
> If you get the error `The remote archive doesn't match the expected checksum` for a dependency pulled from a link (for example, `"tether-drop": "https://github.com/torkelo/drop"`): this is a temporary mismatch. To work around the error (while someone corrects the issue), you can prefix your `yarn install --immutable` command with [`YARN_CHECKSUM_BEHAVIOR=update`](https://yarnpkg.com/advanced/error-codes#yn0018---cache_checksum_mismatch).
After the command has finished, we can start building our source code:
After the command has finished, you can start building the source code:
```
yarn start
```
This command will generate sass theme files, build all external plugins, then build the frontend assets.
Once `yarn start` has built the assets, it will continue to do so whenever any of the core Grafana application files change. This means you don't have to manually build the assets every time you change the code.
This command generates SASS theme files, builds all external plugins, and then builds the frontend assets.
> Troubleshooting: if your first build works, but after pulling updates you see unexpected errors in the "Type-checking in progress..." stage, these can be caused by the [tsbuildinfo cache supporting incremental builds](https://www.typescriptlang.org/tsconfig#incremental). You can `rm tsconfig.tsbuildinfo` and re-try.
After `yarn start` has built the assets, it will continue to do so whenever any of the files change. This means you don't have to manually build the assets every time you change the code.
#### Plugins
> **Troubleshooting:** if your first build works, after pulling updates you may see unexpected errors in the "Type-checking in progress..." stage. These errors can be caused by the [tsbuildinfo cache supporting incremental builds](https://www.typescriptlang.org/tsconfig#incremental). In this case, you can enter `rm tsconfig.tsbuildinfo` and re-try.
If you are looking to contribute to any of the plugins listed below (that are found within the `public/app/plugins` directory) they require running additional commands to watch and rebuild them.
- azuremonitor
- cloud-monitoring
- grafana-postgresql-datasource
- grafana-pyroscope-datasource
- grafana-testdata-datasource
- jaegar
- mysql
- parca
- tempo
- zipkin
To build and watch all these plugins you can run the following command. Note this can be quite resource intensive as it will start separate build processes for each plugin.
```
yarn plugin:build:dev
```
If, instead, you would like to build and watch a specific plugin you can run the following command. Make sure to substitute `<name_of_plugin>` with the plugins name field found in its package.json. e.g. `@grafana-plugins/tempo`.
```
yarn workspace <name_of_plugin> dev
```
Next, we'll build & run the web server that will serve the frontend assets we just built.
Next, we'll explain how to build and run the web server that serves these frontend assets.
### Backend
Build and run the backend by running `make run` in the root directory of the repository. This command compiles the Go source code and starts a web server.
> Are you having problems with [too many open files](#troubleshooting)?
> **Troubleshooting:** Are you having problems with [too many open files](#troubleshooting)?
By default, you can access the web server at `http://localhost:3000/`.
@ -126,14 +102,14 @@ Log in using the default credentials:
When you log in for the first time, Grafana asks you to change your password.
#### Building on Windows
#### Build on Windows
The Grafana backend includes SQLite which requires GCC to compile. So in order to compile Grafana on Windows you need to install GCC. We recommend [TDM-GCC](http://tdm-gcc.tdragon.net/download). Eventually, if you use [Scoop](https://scoop.sh), you can install GCC through that.
The Grafana backend includes SQLite, a database which requires GCC to compile. So in order to compile Grafana on Windows you need to install GCC. We recommend [TDM-GCC](http://tdm-gcc.tdragon.net/download). Eventually, if you use [Scoop](https://scoop.sh), you can install GCC through that.
You can build the back-end as follows:
1. Follow the [instructions](https://github.com/google/wire#installing) to install the Wire tool.
2. Generate code using Wire:
2. Generate code using Wire. For example:
```
# Default Wire tool install path: $GOPATH/bin/wire.exe
@ -146,8 +122,9 @@ You can build the back-end as follows:
go run build.go build
```
The Grafana binaries will be in bin\\windows-amd64.
Alternately, if you wish to use the `make` command, install [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm) and use it in a Unix shell (f.ex. Git Bash).
The Grafana binaries will be installed in `bin\\windows-amd64`.
Alternatively, if you are on Windows and want to use the `make` command, install [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm) and use it in a UNIX shell (for example, Git Bash).
## Test Grafana
@ -155,7 +132,7 @@ The test suite consists of three types of tests: _Frontend tests_, _backend test
### Run frontend tests
We use [jest](https://jestjs.io/) for our frontend tests. Run them using Yarn:
We use [Jest](https://jestjs.io/) for our frontend tests. Run them using Yarn:
```
yarn test
@ -171,7 +148,7 @@ go test -v ./pkg/...
#### On Windows
Running the backend tests on Windows currently needs some tweaking, so use the build.go script:
Running the backend tests on Windows currently needs some tweaking, so use the `build.go` script:
```
go run build.go test
@ -179,19 +156,21 @@ go run build.go test
### Run SQLLite, PostgreSQL and MySQL integration tests
By default, grafana runs SQLite, to run test with SQLite
By default, grafana runs SQLite. To run test with SQLite:
```bash
go test -covermode=atomic -tags=integration ./pkg/...
```
To run PostgreSQL and MySQL integration tests locally, you need to start the docker blocks for MySQL and/or PostgreSQL test data sources by running `make devenv sources=mysql_tests,postgres_tests`. When your test data sources are running, you can execute integration tests by running:
To run PostgreSQL and MySQL integration tests locally, start the Docker blocks for test data sources for MySQL, PostgreSQL, or both, by running `make devenv sources=mysql_tests,postgres_tests`.
When your test data sources are running, you can execute integration tests by running for MySQL:
```bash
make test-go-integration-mysql
```
and/or
For PostgreSQL, you could run:
```bash
make test-go-integration-postgres
@ -199,9 +178,9 @@ make test-go-integration-postgres
### Run end-to-end tests
Grafana uses [Cypress](https://www.cypress.io/) to end-to-end test core features. Core plugins use [Playwright](https://playwright.dev/) to run automated end-to-end tests. You can find more information on how to add end-to-end tests to your core plugin [here](./style-guides/e2e-plugins.md)
Grafana uses [Cypress](https://www.cypress.io/) to end-to-end test core features. Core plugins use [Playwright](https://playwright.dev/) to run automated end-to-end tests. You can find more information on how to add end-to-end tests to your core plugin [in our end-to-end testing style guide](./style-guides/e2e-plugins.md)
#### Running Cypress tests
#### Run Cypress tests
To run all tests in a headless Chromium browser.
@ -231,25 +210,25 @@ yarn e2e:dev
**Note:** If you're using VS Code as your development editor, it's recommended to install the [Playwright test extension](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright). It allows you to run, debug and generate Playwright tests from within the editor. For more information about the extension and how to install it, refer to the [Playwright documentation](https://playwright.dev/docs/getting-started-vscode).
Each version of Playwright needs specific versions of browser binaries to operate. You will need to use the Playwright CLI to install these browsers.
Each version of Playwright needs specific versions of browser binaries to operate. You need to use the Playwright CLI to install these browsers.
```
yarn playwright install chromium
```
To run all tests in a headless Chromium browser and display results in the terminal.
To run all tests in a headless Chromium browser and display results in the terminal:
```
yarn e2e:playwright
```
For a better developer experience, open the Playwright UI where you can easily walk through each step of the test and visually see what was happening before, during and after each step.
For a better developer experience, open the Playwright UI where you can visually walk through each step of the test and see what was happening before, during, and after each step.
```
yarn e2e:playwright:ui
```
To open the HTML reporter for the last test run session.
To open the HTML reporter for the last test run session:
```
yarn e2e:playwright:report
@ -261,7 +240,7 @@ The default configuration, `defaults.ini`, is located in the `conf` directory.
To override the default configuration, create a `custom.ini` file in the `conf` directory. You only need to add the options you wish to override.
Enable the development mode, by adding the following line in your `custom.ini`:
Enable the development mode by adding the following line in your `custom.ini`:
```
app_mode = development
@ -291,7 +270,7 @@ make devenv sources=influxdb,loki
The script generates a Docker Compose file with the databases you specify as `sources`, and runs them in the background.
See the repository for all the [available data sources](/devenv/docker/blocks). Note that some data sources have specific Docker images for macOS, e.g. `nginx_proxy_mac`.
See the repository for all the [available data sources](/devenv/docker/blocks). Note that some data sources have specific Docker images for macOS; for example, `nginx_proxy_mac`.
## Build a Docker image
@ -301,9 +280,9 @@ To build a Docker image, run:
make build-docker-full
```
The resulting image will be tagged as grafana/grafana:dev.
The resulting image will be tagged as `grafana/grafana:dev`.
**Note:** If you are using Docker for macOS, be sure to set the memory limit to be larger than 2 GiB. Otherwise, `grunt build` may fail. The memory limit settings are available under **Docker Desktop** -> **Preferences** -> **Advanced**.
> **Note:** If you use Docker for macOS, be sure to set the memory limit to be larger than 2 GiB. Otherwise, `grunt build` may fail. The memory limit settings are available under **Docker Desktop** -> **Preferences** -> **Advanced**.
## Troubleshooting
@ -311,13 +290,13 @@ Are you having issues with setting up your environment? Here are some tips that
### IDE configuration
Configure your IDE to use the Typescript version from the Grafana repository. The version should match the Typescript version in the package.json file, and is typically at the path `node_modules/.bin/tsc`.
Configure your IDE to use the TypeScript version from the Grafana repository. The version should match the TypeScript version in the `package.json` file, and is typically located at `node_modules/.bin/tsc`.
Previously Grafana used Yarn PnP to install frontend dependencies, which required additional special IDE configuration. This is no longer the case. If you have custom paths in your IDE for ESLint, Prettier, or Typescript, you can now remove them and use the defaults from node_modules.
Previously, Grafana used Yarn PnP to install frontend dependencies, which required additional special IDE configuration. This is no longer the case. If you have custom paths in your IDE for ESLint, Prettier, or TypeScript, you can now remove them and use the defaults from `node_modules`.
### Too many open files when running `make run`
Depending on your environment, you may have to increase the maximum number of open files allowed. For the rest of this section, we will assume you are on a Unix like OS (e.g. Linux/macOS), where you can control the maximum number of open files through the [ulimit](https://ss64.com/bash/ulimit.html) shell command.
Depending on your environment, you may have to increase the maximum number of open files allowed. For the rest of this section, we will assume you are on a UNIX-like OS (for example, Linux or macOS), where you can control the maximum number of open files through the [ulimit](https://ss64.com/bash/ulimit.html) shell command.
To see how many open files are allowed, run:
@ -339,7 +318,7 @@ find ./conf ./pkg ./public/views | wc -l
Another alternative is to limit the files being watched. The directories that are watched for changes are listed in the `.bra.toml` file in the root directory.
To retain your `ulimit` configuration, i.e. so it will be remembered for future sessions, you need to commit it to your command line shell initialization file. Which file this will be depends on the shell you are using, here are some examples:
You can retain your `ulimit` configuration, that is, save it so it will be remembered for future sessions. To do this, commit it to your command line shell initialization file. Which file this is depends on the shell you are using. For example:
- zsh -> ~/.zshrc
- bash -> ~/.bashrc
@ -358,7 +337,7 @@ For some people, typically using the bash shell, ulimit fails with an error simi
ulimit: open files: cannot modify limit: Operation not permitted
```
If that happens to you, chances are you've already set a lower limit and your shell won't let you set a higher one. Try looking in your shell initialization files (~/.bashrc typically), if there's already an ulimit command that you can tweak.
If that happens to you, chances are you've already set a lower limit and your shell won't let you set a higher one. Try looking in your shell initialization files (`~/.bashrc`, typically), to see if there's already an `ulimit` command that you can tweak.
### Getting `AggregateError` when building frontend tests
@ -367,6 +346,6 @@ If you encounter an `AggregateError` when building new tests, this is probably d
## Next steps
- Read our [style guides](/contribute/style-guides).
- Learn how to [Create a pull request](/contribute/create-pull-request.md).
- Learn how to [create a pull request](/contribute/create-pull-request.md).
- Read about the [architecture](architecture).
- Read through the [backend documentation](/contribute/backend/README.md).

18
contribute/drone-pipeline.md
View File

@ -1,15 +1,17 @@
# Making changes to the Drone pipeline
_Only people in the Grafana organization can make changes to the Drone pipeline_
> Only members of the Grafana organization can make changes to the Drone pipeline.
The Drone pipelines are built with [Starlark](https://github.com/bazelbuild/starlark), a language which is similar to Python. The Starlark files are located in [`scripts/drone`](https://github.com/grafana/grafana/tree/main/scripts/drone).
The Drone pipelines are built with [Starlark](https://github.com/bazelbuild/starlark), a similar language to Python. The Starlark files are located in [`scripts/drone`](https://github.com/grafana/grafana/tree/main/scripts/drone).
## Setup
## Drone setup
- Set environment variables `DRONE_SERVER` and `DRONE_TOKEN`, which can be found on your [Drone account](https://drone.grafana.net/account). These are used to verify that only Grafana employees can make changes to the pipelines.
- Install [buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md), and use it to format the Starlark files you edit.
1. Set environment variables `DRONE_SERVER` and `DRONE_TOKEN` found in your [Drone account](https://drone.grafana.net/account). These environment variables are used to verify that only Grafana employees can make changes to the pipelines.
1. Install [buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier/README.md), and use it to format the Starlark files you want to edit.
## Develop
## Drone development
- Open a PR where you can do test runs for your changes. If you need to experiment with secrets, create a PR in the [grafana-ci-sandbox repo](https://github.com/grafana/grafana-ci-sandbox), before opening a PR in the main repo.
- Run `make drone` after making changes to the Starlark files. This builds the `.drone.yml` file.
1. Open a pull request where you can do test runs for your changes. If you need to experiment with secrets, create a pull request in the [`grafana-ci-sandbox repo`](https://github.com/grafana/grafana-ci-sandbox) before opening a pull request in the main repo.
1. Run `make drone` after making changes to the Starlark files. This builds the `.drone.yml` file.
For further questions, reach out to the `grafana-release-guild` squad.

12
contribute/feature-toggles.md
View File

@ -1,15 +1,17 @@
# Feature toggle guide
This guide helps you get started adding your feature behind a feature flag in Grafana.
This guide helps you to add your feature behind a _feature flag_, code that lets you enable or disable a feature without redeploying Grafana.
## Steps to adding a feature toggle
1. Define the feature toggle in [registry.go](../pkg/services/featuremgmt/registry.go). To see what each feature stage means, look at the comments [here](../pkg/services/featuremgmt/features.go). If you are a community member, use the [CODEOWNERS](../.github/CODEOWNERS) file to determine which team owns the package you are updating.
2. Run the go tests mentioned at the top of [this file](../pkg/services/featuremgmt/toggles_gen.go). This will generate all the additional files needed: `toggles_gen` for the backend, `grafana-data` for the frontend, and docs. You can run the test by running `make gen-feature-toggles`.
1. Define the feature toggle in [registry.go](../pkg/services/featuremgmt/registry.go). To see what each feature stage means, look at the [related comments](../pkg/services/featuremgmt/features.go). If you are a community member, use the [CODEOWNERS](../.github/CODEOWNERS) file to determine which team owns the package you are updating.
2. Run the Go tests mentioned at the top of [this file](../pkg/services/featuremgmt/toggles_gen.go). This generates all the additional files needed: `toggles_gen` for the backend, `grafana-data` for the frontend, and docs. To run the test, run `make gen-feature-toggles`.
## How to use it in the code
## How to use the toggle in your code
Once your feature toggle is defined, you can then wrap your feature around a check if the feature flag is enabled on that Grafana instance. Here are examples of how to do that:
Once your feature toggle is defined, you can then wrap your feature around a check if the feature flag is enabled on that Grafana instance.
Examples:
- [Backend](https://github.com/grafana/grafana/blob/feb2b5878b3e3ec551d64872c35edec2a0187812/pkg/services/authn/clients/session.go#L57): Use the `IsEnabled` function and pass in your feature toggle.
- [Frontend](https://github.com/grafana/grafana/blob/feb2b5878b3e3ec551d64872c35edec2a0187812/public/app/features/search/service/folders.ts#L14): Check the config for your feature toggle.