Docs: Simplify README (#19702)

* Simplify README * Fix review comments * Rename Developer guide
2025-02-11 16:15:42 -06:00 · 2019-10-08 17:22:37 +02:00 · 2019-10-08 17:22:37 +02:00 · 096e0e761e
commit 096e0e761e
parent 9bff81e590
5 changed files with 94 additions and 207 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -52,7 +52,7 @@ Unsure where to begin contributing to Grafana? Start by browsing issues labeled
 - [Beginner-friendly](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22) issues are generally straightforward to complete.
 - [Help wanted](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) issues are problems we would like the community to help us with regardless of complexity.

-If you're looking to make a code change, see how to set up your environment for [local development](contribute/development.md).
+If you're looking to make a code change, see how to set up your environment for [local development](contribute/developer-guide.md).

 When you're ready to contribute, it's time to [Create a pull request](/contribute/pull-request.md).

@ -69,6 +69,6 @@ Before we can accept your pull request, you need to [sign our CLA](https://grafa

 ## Where do I go from here?

- Set up your [development environment](contribute/development.md).
+- Set up your [development environment](contribute/developer-guide.md).
 - Learn how to [contribute documentation](contribute/documentation.md).
 - Get started [developing plugins](https://grafana.com/docs/plugins/developing/development/) for Grafana.
--- a/README.md
+++ b/README.md
@ -1,222 +1,45 @@
-# [Grafana](https://grafana.com) [![Circle CI](https://circleci.com/gh/grafana/grafana.svg?style=svg)](https://circleci.com/gh/grafana/grafana) [![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana)](https://goreportcard.com/report/github.com/grafana/grafana) 
+![Grafana](docs/logo-horizontal.png)

-[Website](https://grafana.com) |
-[Twitter](https://twitter.com/grafana) |
-[Community & Forum](https://community.grafana.com)
+The open-source platform for monitoring and observability.

-Grafana is an open source, feature rich metrics dashboard and graph editor for
-Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
+[![License](https://img.shields.io/github/license/grafana/grafana)](LICENSE)
+[![Circle CI](https://img.shields.io/circleci/build/gh/grafana/grafana)](https://circleci.com/gh/grafana/grafana)
+[![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana)](https://goreportcard.com/report/github.com/grafana/grafana)

-<!---
-![](http://docs.grafana.org/assets/img/features/dashboard_ex1.png)
-->
+Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture:

-## Installation
+- **Visualize:** Fast and flexible client side graphs with a multitude of options. Panel plugins for many different way to visualize metrics and logs.
+- **Dynamic Dashboards:** Create dynamic & reusable dashboards with template variables that appear as dropdowns at the top of the dashboard.
+- **Explore Metrics:** Explore your data through ad-hoc queries and dynamic drilldown. Split view and compare different time ranges, queries and data sources side by side.
+- **Explore Logs:** Experience the magic of switching from metrics to logs with preserved label filters. Quickly search through all your logs or streaming them live.
+- **Alerting:** Visually define alert rules for your most important metrics. Grafana will continuously evaluate and send notifications to systems like Slack, PagerDuty, VictorOps, OpsGenie.
+- **Mixed Data Sources:** Mix different data sources in the same graph! You can specify a data source on a per-query basis. This works for even custom datasources.

-Head to [docs.grafana.org](http://docs.grafana.org/installation/) for documentation or [grafana.com/get](https://grafana.com/get) to download the latest release.
+## Get started

-## Documentation & Support
+- [Get Grafana](https://grafana.com/get)
+- [Installation guides](http://docs.grafana.org/installation/)

-Be sure to read the [Getting Started](http://docs.grafana.org/guides/gettingstarted/) guide and the other feature guides.
+Unsure if Grafana is for you? Watch Grafana in action on [play.grafana.org](https://play.grafana.org/)!

-## Run from master
+## Documentation

-If you want to build a package yourself, or contribute - here is a guide for how to do that. You can always find
-the latest master builds [here](https://grafana.com/grafana/download).
+The Grafana documentation is available at [grafana.com/docs](https://grafana.com/docs/).

-### Dependencies
+## Contributing

- Go (Latest Stable)
- Node.js LTS
-  - yarn [`npm install -g yarn`]
+If you're interested in contributing to the Grafana project:

-### Get the project
+- Start by reading the [Contributing guide](/CONTRIBUTING.md).
+- Learn how to set up your local environment, in our [Developer guide](/contribute/developer-guide.md).
+- Explore our [beginner-friendly issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22).

-**The project located in the go-path will be your working directory.**
+## Get involved

-```bash
-go get github.com/grafana/grafana
-cd $GOPATH/src/github.com/grafana/grafana
-```
-
-### Run and rebuild on source change
-
-#### Backend
-
-To run the backend and rebuild on source change:
-
-```bash
-make run
-```
-
-#### Frontend
-Install front-end dependencies first:
-
-```bash
-yarn install --pure-lockfile
-```
-
-Rebuild on file change, and serve them by Grafana's webserver (http://localhost:3000):
-
-```bash
-yarn start
-```
-
-Build the assets, rebuild on file change with Hot Module Replacement (HMR), and serve them by webpack-dev-server (http://localhost:3333):
-
-```bash
-yarn start:hot
-# OR set a theme
-env GRAFANA_THEME=light yarn start:hot
-```
-
-_Note: HMR for Angular is not supported. If you edit files in the Angular part of the app, the whole page will reload._
-
-Run tests and rebuild on source change:
-
-```bash
-yarn jest
-```
-
-**Open grafana in your browser (default: e.g. `http://localhost:3000`) and login with admin user (default: `user/pass = admin/admin`).**
-
-### Building
-
-#### The backend
-
-```bash
-go run build.go setup
-go run build.go build
-```
-
-#### Frontend assets
-
-_For this you need Node.js (LTS version)._
-
-```bash
-yarn install --pure-lockfile
-```
-
-### Building a Docker image
-
-There are two different ways to build a Grafana docker image. If your machine is setup for Grafana development and you run linux/amd64 you can build just the image. Otherwise, there is the option to build Grafana completely within Docker.
-
-Run the image you have built using: `docker run --rm -p 3000:3000 grafana/grafana:dev`
-
-#### Building on linux/amd64 (fast)
-
-1. Build the frontend `go run build.go build-frontend`.
-2. Build the docker image `make build-docker-dev`.
-
-The resulting image will be tagged as `grafana/grafana:dev`.
-
-#### Building anywhere (slower)
-
-Choose this option to build on platforms other than linux/amd64 and/or not have to setup the Grafana development environment.
-
-1. `make build-docker-full` or `docker build -t grafana/grafana:dev`.
-
-The resulting image will be tagged as `grafana/grafana:dev`.
-
-Notice: If you are using Docker for MacOS, be sure to set the memory limit to be larger than 2 GiB (at docker -> Preferences -> Advanced), otherwise `grunt build` may fail.
-
-## Development
-
-### Dev config
-
-Create a custom.ini in the conf directory to override default configuration options.
-You only need to add the options you want to override. Config files are applied in the order of:
-
-1. grafana.ini
-1. custom.ini
-
-In your custom.ini uncomment (remove the leading `;`) sign. And set `app_mode = development`.
-
-### Running tests
-
-#### Frontend
-
-Execute all frontend tests:
-
-```bash
-yarn test
-```
-
-Write and watch frontend tests:
-
- Start watcher: `yarn jest`.
- Jest runs all test files that end with the name ".test.ts".
-
-#### Backend
-
-```bash
-# Run Golang tests using sqlite3 as database (default)
-go test ./pkg/...
-```
-
-##### Running the MySQL or Postgres backend tests:
-
-Run these by setting `GRAFANA_TEST_DB` in your environment.
-
- `GRAFANA_TEST_DB=mysql` to test MySQL
- `GRAFANA_TEST_DB=postgres` to test Postgres
-
-Follow the instructions in `./devenv` to spin up test containers running the appropriate databases with `docker-compose`
- Use `docker/blocks/mysql_tests` or `docker/blocks/postgres_tests` as appropriate.
-
-```bash
-# MySQL
-# Tests can only be ran in one Go package at a time due to clashing db queries. To run MySQL tests for the "pkg/services/sqlstore" package, run:
-GRAFANA_TEST_DB=mysql go test ./pkg/services/sqlstore/...
-
-# Or run all the packages using the circle CI scripts. This method will be slower as the scripts will run all the tests, including the integration tests.
-./scripts/circle-test-mysql.sh
-```
-
-```bash
-# Postgres
-# Tests can only be ran in one Go package at a time due to clashing db queries. To run Postgres tests for the "pkg/services/sqlstore" package, run:
-GRAFANA_TEST_DB=postgres go test ./pkg/services/sqlstore/...
-
-# Or run all the packages using the circle CI scripts. This method will be slower as the scripts will run all the tests, including the integration tests.
-./scripts/circle-test-postgres.sh
-```
-
-#### End-to-end
-
-Execute all end-to-end tests:
-
-```bash
-yarn e2e-tests
-```
-
-Execute all end-to-end tests using using a specific url:
-
-```bash
-ENV BASE_URL=http://localhost:3333 yarn e2e-tests
-```
-
-Debugging all end-to-end tests (BROWSER=1 starts the browser and SLOWMO=1 delays each puppeteer operation by 100ms):
-
-```bash
-ENV BROWSER=1 SLOWMO=1 yarn e2e-tests
-```
-
-### Data source and dashboard provisioning
-
-[Here](https://github.com/grafana/grafana/tree/master/devenv) you can find helpful scripts and docker-compose setup
-that will populate your dev environment for quicker testing and experimenting.
-
-## Contribute
-
-If you have any ideas for improvement or have found a bug, do not hesitate to open an issue.
-And if you have time, clone this repo and submit a pull request to help me make Grafana the kickass metrics and devops dashboard we all dream about!
-
-Read the [contributing](https://github.com/grafana/grafana/blob/master/CONTRIBUTING.md) guide then check the [`beginner friendly`](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3A%22beginner+friendly%22) label to find issues that are easy and that we would like help with.
-
-## Plugin development
-
-Checkout the [Plugin Development Guide](http://docs.grafana.org/plugins/developing/development/) and checkout the [PLUGIN_DEV.md](https://github.com/grafana/grafana/blob/master/PLUGIN_DEV.md) file for changes in Grafana that relate to plugin development.
+- Follow [@grafana on Twitter](https://twitter.com/grafana/)
+- Read and subscribe to the [Grafana blog](https://grafana.com/blog/)
+- If you have a specific question, check out our [discussion forums](https://community.grafana.com/).
+- For general discussions, join us on the [official Slack](http://slack.raintank.io/) team.

 ## License

--- a/contribute/developer-guide.md
+++ b/contribute/developer-guide.md
--- a/docs/logo-horizontal.png
+++ b/docs/logo-horizontal.png
--- a/docs/logo-swirl.svg
+++ b/docs/logo-swirl.svg
@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 23.0.4, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 85.12 92.46" style="enable-background:new 0 0 85.12 92.46;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:url(#SVGID_1_);}
+</style>
+<linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="42.562" y1="113.2595" x2="42.562" y2="28.7828">
+	<stop  offset="0" style="stop-color:#FFF200"/>
+	<stop  offset="1" style="stop-color:#F15A29"/>
+</linearGradient>
+<path class="st0" d="M85.01,40.8c-0.14-1.55-0.41-3.35-0.93-5.32c-0.51-1.97-1.28-4.13-2.39-6.37c-1.12-2.24-2.57-4.57-4.47-6.82
+	c-0.74-0.88-1.54-1.76-2.42-2.6c1.3-5.17-1.59-9.65-1.59-9.65c-4.98-0.31-8.14,1.54-9.31,2.39c-0.2-0.08-0.39-0.17-0.59-0.25
+	c-0.85-0.34-1.72-0.66-2.61-0.95c-0.89-0.28-1.81-0.54-2.74-0.76c-0.94-0.22-1.89-0.4-2.86-0.55c-0.17-0.03-0.34-0.05-0.51-0.07
+	C52.41,2.9,46.18,0,46.18,0c-6.95,4.41-8.27,10.57-8.27,10.57s-0.03,0.14-0.07,0.36c-0.38,0.11-0.77,0.22-1.15,0.34
+	c-0.53,0.16-1.06,0.36-1.59,0.55c-0.53,0.21-1.06,0.41-1.58,0.64c-1.05,0.45-2.09,0.96-3.1,1.53c-0.99,0.55-1.95,1.16-2.9,1.82
+	c-0.14-0.06-0.24-0.11-0.24-0.11c-9.62-3.68-18.17,0.75-18.17,0.75c-0.78,10.24,3.84,16.68,4.76,17.86
+	c-0.23,0.63-0.44,1.27-0.64,1.92c-0.71,2.32-1.24,4.7-1.57,7.16c-0.05,0.35-0.09,0.71-0.13,1.07C2.63,48.84,0,57.84,0,57.84
+	c7.42,8.53,16.07,9.06,16.07,9.06c0.01-0.01,0.02-0.01,0.02-0.02c1.1,1.96,2.37,3.83,3.8,5.57c0.6,0.73,1.23,1.43,1.88,2.11
+	c-2.71,7.74,0.38,14.18,0.38,14.18c8.26,0.31,13.69-3.61,14.83-4.52c0.82,0.28,1.66,0.53,2.5,0.74c2.54,0.65,5.14,1.04,7.74,1.15
+	c0.65,0.03,1.3,0.04,1.95,0.04l0.31,0l0.21-0.01l0.41-0.01l0.4-0.02l0.01,0.01c3.89,5.55,10.74,6.34,10.74,6.34
+	c4.87-5.13,5.15-10.22,5.15-11.33l0,0c0,0,0-0.04,0-0.07c0-0.09,0-0.15,0-0.15s0,0,0,0c0-0.08-0.01-0.15-0.01-0.23
+	c1.02-0.72,2-1.49,2.92-2.31c1.95-1.76,3.65-3.77,5.06-5.93c0.13-0.2,0.26-0.41,0.39-0.62c5.51,0.32,9.39-3.41,9.39-3.41
+	c-0.91-5.74-4.18-8.54-4.87-9.07l0,0c0,0-0.03-0.02-0.07-0.05c-0.04-0.03-0.06-0.05-0.06-0.05l0,0c-0.04-0.02-0.08-0.05-0.12-0.08
+	c0.03-0.35,0.06-0.69,0.08-1.04c0.04-0.62,0.06-1.24,0.06-1.85l0-0.46l0-0.23l0-0.12c0-0.16,0-0.1,0-0.16l-0.02-0.38l-0.03-0.52
+	c-0.01-0.18-0.02-0.34-0.04-0.5c-0.01-0.16-0.03-0.32-0.05-0.48l-0.06-0.48l-0.07-0.47c-0.09-0.63-0.21-1.26-0.36-1.88
+	c-0.58-2.47-1.54-4.82-2.82-6.93c-1.28-2.11-2.86-3.98-4.65-5.56c-1.79-1.58-3.79-2.85-5.9-3.79c-2.1-0.95-4.31-1.55-6.51-1.83
+	c-1.1-0.14-2.2-0.2-3.28-0.19l-0.41,0.01l-0.1,0c-0.03,0-0.15,0-0.14,0l-0.17,0.01l-0.4,0.03c-0.15,0.01-0.31,0.02-0.45,0.04
+	c-0.56,0.05-1.11,0.13-1.66,0.23c-2.18,0.41-4.24,1.2-6.06,2.28c-1.82,1.09-3.39,2.45-4.68,3.98c-1.28,1.54-2.28,3.24-2.96,5
+	c-0.69,1.76-1.07,3.58-1.18,5.35c-0.03,0.44-0.04,0.88-0.03,1.32c0,0.11,0,0.22,0.01,0.33l0.01,0.35c0.02,0.21,0.03,0.42,0.05,0.63
+	c0.09,0.9,0.25,1.75,0.49,2.58c0.48,1.66,1.25,3.15,2.2,4.43c0.95,1.28,2.08,2.33,3.28,3.15c1.2,0.82,2.49,1.41,3.76,1.79
+	c1.27,0.38,2.54,0.54,3.74,0.53c0.15,0,0.3,0,0.44-0.01c0.08,0,0.16-0.01,0.24-0.01c0.08,0,0.16-0.01,0.24-0.01
+	c0.13-0.01,0.25-0.03,0.38-0.04c0.03,0,0.07-0.01,0.11-0.01l0.12-0.02c0.08-0.01,0.15-0.02,0.23-0.03c0.16-0.02,0.29-0.05,0.43-0.08
+	c0.14-0.03,0.28-0.05,0.42-0.09c0.27-0.06,0.54-0.14,0.8-0.22c0.52-0.17,1.01-0.38,1.46-0.61c0.45-0.23,0.87-0.5,1.26-0.77
+	c0.11-0.08,0.22-0.16,0.33-0.25c0.42-0.33,0.48-0.94,0.15-1.35c-0.29-0.36-0.79-0.45-1.19-0.23c-0.1,0.05-0.2,0.11-0.3,0.16
+	c-0.35,0.17-0.71,0.32-1.09,0.45c-0.39,0.12-0.79,0.22-1.2,0.29c-0.21,0.03-0.42,0.06-0.63,0.08c-0.11,0.01-0.21,0.02-0.32,0.02
+	c-0.11,0-0.22,0.01-0.32,0.01c-0.1,0-0.21,0-0.31-0.01c-0.13-0.01-0.26-0.01-0.39-0.02c0,0-0.07,0-0.01,0l-0.04,0L51.4,61.6
+	c-0.06-0.01-0.12-0.01-0.17-0.02c-0.12-0.01-0.23-0.03-0.35-0.04c-0.93-0.13-1.88-0.4-2.79-0.82c-0.91-0.41-1.79-0.98-2.57-1.69
+	c-0.79-0.71-1.48-1.56-2.01-2.52c-0.54-0.96-0.92-2.03-1.09-3.16c-0.09-0.56-0.13-1.14-0.11-1.71c0.01-0.16,0.01-0.31,0.02-0.47
+	c0,0.04,0-0.02,0-0.03l0-0.06l0.01-0.12c0.01-0.08,0.01-0.15,0.02-0.23c0.03-0.31,0.08-0.62,0.13-0.92
+	c0.43-2.45,1.65-4.83,3.55-6.65c0.47-0.45,0.98-0.87,1.53-1.25c0.55-0.37,1.12-0.7,1.73-0.98c0.6-0.28,1.23-0.5,1.88-0.68
+	c0.65-0.17,1.31-0.29,1.98-0.35c0.34-0.03,0.67-0.04,1.01-0.04c0.09,0,0.16,0,0.23,0l0.27,0.01l0.17,0.01c0.07,0,0,0,0.03,0l0.07,0
+	l0.27,0.02c0.73,0.06,1.46,0.16,2.17,0.32c1.43,0.32,2.83,0.85,4.13,1.57c2.6,1.44,4.81,3.69,6.17,6.4c0.69,1.35,1.16,2.81,1.4,4.31
+	c0.06,0.38,0.1,0.76,0.13,1.14l0.02,0.29l0.01,0.29c0.01,0.1,0.01,0.19,0.01,0.29c0,0.09,0.01,0.2,0,0.27l0,0.25l-0.01,0.28
+	c-0.01,0.19-0.02,0.49-0.03,0.67c-0.03,0.42-0.07,0.83-0.12,1.24c-0.05,0.41-0.12,0.82-0.19,1.22c-0.08,0.4-0.17,0.81-0.27,1.21
+	c-0.2,0.8-0.46,1.59-0.76,2.36c-0.61,1.54-1.42,3-2.4,4.36c-1.96,2.7-4.64,4.9-7.69,6.29c-1.52,0.69-3.13,1.19-4.78,1.47
+	c-0.82,0.14-1.66,0.22-2.5,0.25l-0.15,0.01l-0.13,0l-0.27,0l-0.41,0l-0.21,0c0.11,0-0.02,0-0.01,0l-0.08,0
+	c-0.45-0.01-0.9-0.03-1.34-0.07c-1.79-0.13-3.55-0.45-5.27-0.95c-1.71-0.49-3.38-1.16-4.95-2c-3.14-1.68-5.95-3.98-8.15-6.76
+	c-1.11-1.38-2.07-2.87-2.87-4.43c-0.8-1.56-1.42-3.2-1.89-4.88c-0.46-1.68-0.75-3.39-0.86-5.12l-0.02-0.32l-0.01-0.08l0-0.07l0-0.14
+	l-0.01-0.28l0-0.07l0-0.1l0-0.2l-0.01-0.4l0-0.08c0,0.01,0,0.01,0-0.03l0-0.16c0-0.21,0.01-0.42,0.01-0.63
+	c0.03-0.85,0.1-1.73,0.21-2.61c0.11-0.88,0.26-1.76,0.44-2.63c0.18-0.87,0.39-1.74,0.64-2.59c0.49-1.71,1.1-3.36,1.82-4.92
+	c1.44-3.12,3.34-5.88,5.61-8.09c0.57-0.55,1.16-1.08,1.77-1.57c0.61-0.49,1.25-0.95,1.9-1.37c0.65-0.43,1.32-0.82,2.02-1.18
+	c0.34-0.19,0.7-0.35,1.05-0.52c0.18-0.08,0.36-0.16,0.53-0.24c0.18-0.08,0.36-0.16,0.54-0.23c0.72-0.3,1.46-0.56,2.21-0.8
+	c0.19-0.06,0.38-0.11,0.56-0.17c0.19-0.06,0.38-0.1,0.57-0.16c0.38-0.11,0.76-0.2,1.14-0.29c0.19-0.05,0.39-0.08,0.58-0.13
+	c0.19-0.04,0.38-0.08,0.58-0.12c0.19-0.04,0.39-0.07,0.58-0.11l0.29-0.05l0.29-0.04c0.2-0.03,0.39-0.06,0.59-0.09
+	c0.22-0.04,0.44-0.05,0.66-0.09c0.18-0.02,0.48-0.06,0.65-0.08c0.14-0.01,0.28-0.03,0.41-0.04l0.28-0.03l0.14-0.01l0.16-0.01
+	c0.22-0.01,0.44-0.03,0.66-0.04l0.33-0.02c0,0,0.12,0,0.02,0l0.07,0l0.14-0.01c0.19-0.01,0.38-0.02,0.56-0.03
+	c0.75-0.02,1.5-0.02,2.24,0c1.48,0.06,2.93,0.22,4.34,0.48c2.82,0.53,5.49,1.43,7.89,2.62c2.41,1.18,4.57,2.63,6.44,4.2
+	c0.12,0.1,0.23,0.2,0.35,0.3c0.11,0.1,0.23,0.2,0.34,0.3c0.23,0.2,0.44,0.41,0.66,0.61c0.22,0.2,0.43,0.41,0.64,0.62
+	c0.2,0.21,0.41,0.41,0.61,0.63c0.8,0.84,1.53,1.69,2.19,2.55c1.33,1.71,2.39,3.44,3.24,5.07c0.05,0.1,0.11,0.2,0.16,0.3
+	c0.05,0.1,0.1,0.2,0.15,0.3c0.1,0.2,0.2,0.4,0.29,0.6c0.09,0.2,0.19,0.39,0.27,0.59c0.09,0.2,0.17,0.39,0.25,0.58
+	c0.32,0.76,0.61,1.49,0.84,2.18c0.39,1.11,0.67,2.11,0.89,2.98c0.09,0.35,0.42,0.58,0.78,0.55c0.37-0.03,0.66-0.34,0.66-0.71
+	C85.14,43.15,85.11,42.05,85.01,40.8z"/>
+</svg>