This guide helps you get started developing Grafana.
Before you begin, you might want to read [How to contribute to Grafana as a junior dev](https://medium.com/@ivanahuckova/how-to-contribute-to-grafana-as-junior-dev-c01fe3064502) by [Ivana Huckova](https://medium.com/@ivanahuckova).
## Dependencies
Make sure you have the following dependencies installed before moving on to set up your developer environment:
Make sure you have the following dependencies installed before setting up your developer environment:
-[Git](https://git-scm.com/)
-[Go](https://golang.org/dl/)
...
...
@@ -49,13 +52,13 @@ After the command has finished, we can start building our source code:
yarn start
```
Once `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 whenever you've made a change to the code.
Once `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 whenever every time you change the code.
Next, we'll build the web server that will serve the frontend assets we just built.
### Backend
Build and run the backend, by running `make run` in the root directory of the repository. This command will compile the Go source code, and start a web server.
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.
By default, you can access the web server at `http://localhost:3000/`.
...
...
@@ -65,11 +68,11 @@ Log in using the default credentials:
| -------- | -------- |
| `admin` | `admin` |
When you log in for the first time, Grafana will ask you to change your password.
When you log in for the first time, Grafana asks you to change your password.
## Test Grafana
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 jest
...
...
@@ -91,7 +94,7 @@ To set up data sources for your development environment, go to the `devenv` dire
cd devenv
```
Run the `setup.sh` script to setup a set of data sources and dashboards in your local Grafana. The script creates a set of data sources called **gdev-\<type\>**, and a set of dashboards located in a folder called **gdev dashboards**.
Run the `setup.sh` script to set up a set of data sources and dashboards in your local Grafana instance. The script creates a set of data sources called **gdev-\<type\>**, and a set of dashboards located in a folder called **gdev dashboards**.
Some of the data sources require databases to run in the background.
...
...
@@ -111,4 +114,3 @@ See the repository for all the [available data sources](https://github.com/grafa
- Learn how to [Create a pull request](/contribute/pull-request.md).
- Read [How to contribute to Grafana as a junior dev](https://medium.com/@ivanahuckova/how-to-contribute-to-grafana-as-junior-dev-c01fe3064502) by [Ivana Huckova](https://medium.com/@ivanahuckova).
@@ -6,37 +6,33 @@ This documents guides you through the process of contributing to the Grafana doc
If you’re unsure about where to start, check out some of our [open docs issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fdocs).
Sometimes it can be difficult to understand an issue when you're just getting started. We strive to keep a collection of [beginner-friendly issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fdocs+label%3A"beginner+friendly") that is more suitable for first-time contributors.
Sometimes it can be difficult to understand an issue when you're just getting started. Check out the [beginner-friendly issues](https://github.com/grafana/grafana/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fdocs+label%3A"beginner+friendly") for tasks suitable for first-time contributors.
When you’ve found an issue you want to work on, you’re encouraged to comment on the issue to let other people know you intend to work on it.
When you’ve found an issue you want to work on, please comment on the issue to let other people know you intend to work on it.
If you encounter any misspellings, or violations to the style guide, please let us know by submitting an issue.
If you encounter any misspellings or violations to the style guide, please let us know by submitting an issue (or just fix them if they are minor changes).
On every page in the [documentation](https://grafana.com/docs/)there are two links:
On every page in the [documentation](https://grafana.com/docs/)are two links in the upper right corner:
-**Edit this page** takes you directly to the file on GitHub where you can contribute a fix.
-**Request doc changes** prepares an issue on GitHub with relevant information already filled in.
## Community
## Join our community
For general discussions on documentation, you’re welcome to join the `#docs` channel on our [public Grafana Slack](http://slack.raintank.io) team.
## Guidelines
## Style and formatting
All Grafana documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown), and can be found in the [docs](https://github.com/grafana/grafana/tree/master/docs) directory in the [Grafana GitHub repository](https://github.com/grafana/grafana). The [documentation website](https://grafana.com/docs) is generated with [Hugo](https://gohugo.io) which uses [Blackfriday](https://github.com/russross/blackfriday) as its Markdown rendering engine.
### Structure
### Documentation structure
The documentation is organized into topics, called _sections_.
The Grafana documentation is organized into topics, called _sections_. You can take a look at the current build at [grafana.com/docs/](https://grafana.com/docs/).
Each top-level section is located under the [docs/sources](https://github.com/grafana/grafana/tree/master/docs/sources) directory. Subsections are added by creating a subdirectory in the directory of the parent section.
For each section, a`_index.md` file is used to provide an overview of the topic.
For each section, an `_index.md` file provides an overview of the topic.
### Style guide
The [codespell](https://github.com/codespell-project/codespell) tool is run for every change to catch common misspellings.
- "Open source" should be hyphenated when used as an adjective, e.g. _open-source software_. The open form should be preferred when used as a noun, e.g. _Grafana is open source_.
- Use "data source" instead of "datasource" unless used as an identifier, in code or as part of URLs.
- Acronyms should be uppercased, e.g. URL, DNS, or TCP/IP.
Refer to the [Documentation style guide](style-guides/documentation-style-guide.md) for information about Grafana style, word choice, and grammar conventions.
@@ -4,14 +4,20 @@ This style guide applies to all documentation created for Grafana products.
## Contributing
This style guide is a living document. Add to it whenever a style decision is made or question is answered.
The *Documentation style guide* is a living document. Add to it whenever a style decision is made or a question is answered regarding style, grammar, or word choice.
## Published guides
For all items not covered in this guide, refer to the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) and the [Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html).
## Spelling
The [codespell](https://github.com/codespell-project/codespell) tool is run for every change to catch common misspellings.
## Grafana-specific style
The following sections provide general guidelines on topics specific to Grafana documentation. Note that for the most part, these are *guidelines*, not rigid rules. If you have questions, ask in the #docs channel of Grafana Slack.
### General
* Use active voice. Avoid passive voice.
...
...
@@ -68,3 +74,25 @@ Two words, not one
**Exceptions:**
* "datasource" used as an identifier
* "datasource" in a URL
#### display (verb)
*Display* is a transitive verb, which means it always needs a direct object.
* Correct, active voice: Grafana displays your list of active alarms.
* Correct, but passive voice: Your list of active alarms is displayed.
* Incorrect: The list of active alarms displays.
#### open source, open-source
Hyphenate when used as an adjective. For example: _open-source software._
Do not hyphenate when it is used as a noun. For example: _Open source is the best way to develop software._
#### setup, set up
Two words if used as a verb, one word if used as a noun.
