Skip to content

N
nexpie-grafana-theme
Commit 76598cc8 by Daniel Lee
Options

docs: fix merge conflicts

parents 55d7fbf0 651fac3e
Showing with 63 additions and 25 deletions
contribute/developer-guide.md
...@@ -2,9 +2,12 @@ ...@@ -2,9 +2,12 @@
This guide helps you get started developing Grafana. 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 ## 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/) - [Git](https://git-scm.com/)
- [Go](https://golang.org/dl/) - [Go](https://golang.org/dl/)
...@@ -49,13 +52,13 @@ After the command has finished, we can start building our source code: ...@@ -49,13 +52,13 @@ After the command has finished, we can start building our source code:
yarn start 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. Next, we'll build the web server that will serve the frontend assets we just built.
### Backend ### 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.
> Are you having problems with [too many open files](#troubleshooting)? > Are you having problems with [too many open files](#troubleshooting)?
...@@ -67,7 +70,7 @@ Log in using the default credentials: ...@@ -67,7 +70,7 @@ Log in using the default credentials:
| -------- | -------- | | -------- | -------- |
| `admin` | `admin` | | `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 ## Test Grafana
...@@ -75,7 +78,7 @@ The test suite consists of three types of tests: _Frontend tests_, _backend test ...@@ -75,7 +78,7 @@ The test suite consists of three types of tests: _Frontend tests_, _backend test
### Run frontend tests ### 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 jest yarn jest
...@@ -132,7 +135,7 @@ To set up data sources for your development environment, go to the [devenv](deve ...@@ -132,7 +135,7 @@ To set up data sources for your development environment, go to the [devenv](deve
cd devenv 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. Some of the data sources require databases to run in the background.
...@@ -195,7 +198,6 @@ Another alternative is to limit the files being watched. The directories that ar ...@@ -195,7 +198,6 @@ Another alternative is to limit the files being watched. The directories that ar
## Next steps ## Next steps
- [Create a pull request](/contribute/pull-request.md) - Read our [style guides](/contribute/style-guides).
- [Style guides](/contribute/style-guides) - Learn how to [Create a pull request](/contribute/pull-request.md).
- [Architecture](architecture) - [Architecture](architecture).
- [How to contribute to Grafana as a junior dev](https://medium.com/@ivanahuckova/how-to-contribute-to-grafana-as-junior-dev-c01fe3064502)
contribute/documentation.md
...@@ -6,36 +6,36 @@ This documents guides you through the process of contributing to the Grafana doc ...@@ -6,36 +6,36 @@ 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). 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. Refer to this list of [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. - **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. - **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. 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. 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. 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 ### Style guide
A [style guide](https://github.com/grafana/grafana/blob/master/style_guides/documentation-style-guide.md), which applies to all documentation created by the Grafana project, is located in the [Grafana GitHub repository](https://github.com/grafana/grafana). Refer to the [Documentation style guide](style-guides/documentation-style-guide.md) for information about Grafana style, word choice, and grammar conventions.
### Spelling ### Spelling
......
contribute/pull-request.md
...@@ -16,7 +16,7 @@ If this is your first time contributing to an open-source project on GitHub, mak ...@@ -16,7 +16,7 @@ If this is your first time contributing to an open-source project on GitHub, mak
To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines: To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines:
- Title and description matches the implementation. - Title and description matches the implementation.
- Commits within the pull request follow the [style guide](#style-guide). - Commits within the pull request follow the [Formatting guidelines](#Formatting-guidelines).
- The pull request closes one related issue. - The pull request closes one related issue.
- The pull request contains necessary tests that verify the intended behavior. - The pull request contains necessary tests that verify the intended behavior.
- If your pull request has conflicts, rebase your branch onto the master branch. - If your pull request has conflicts, rebase your branch onto the master branch.
...@@ -79,11 +79,12 @@ For changes to data sources, the area should be the name of the data source, e.g ...@@ -79,11 +79,12 @@ For changes to data sources, the area should be the name of the data source, e.g
For changes to panels, the area should be the name of the panel, suffixed with Panel, e.g., GraphPanel, SinglestatPanel, and TablePanel. For changes to panels, the area should be the name of the panel, suffixed with Panel, e.g., GraphPanel, SinglestatPanel, and TablePanel.
**Example** **Examples**
- `Build: Support publishing MSI to grafana.com` - `Build: Support publishing MSI to grafana.com`
- `Explore: Add Live option for supported data sources` - `Explore: Add Live option for supported data sources`
- `GraphPanel: Fix legend sorting issues` - `GraphPanel: Fix legend sorting issues`
- `Docs: Changed url to URL in all documentation files`
### Pull request titles ### Pull request titles
......
contribute/style-guides/README.md
# Style guides # Style guides
This section contains style guides for the Grafana software project and documentation. This section contains style guides for the Grafana software project and Grafana documentation.
- [Backend style guide](backend.md): Provides guidance on how to style and format backend functionality and code. - [Backend style guide](backend.md): Provides guidance on how to style and format backend functionality and code.
- [Documentation style guide](documentation-style-guide.md): Provides guidance on how to style and format documentation. - [Documentation style guide](documentation-style-guide.md): Provides guidance on how to style and format Grafana documentation.
- [Frontend style guide](frontend.md): Provides guidance on how to style and format the user-facing functionality and code. - [Frontend style guide](frontend.md): Provides guidance on how to style and format the user-facing functionality and code.
- [Redux framework](redux.md): Provides guidance on designing the Grafana redux framework. - [Redux framework](redux.md): Provides guidance on designing the Grafana redux framework.
- [Themes style guide](themes.md): Provides guidance on designing and updating Grafana themes. - [Themes style guide](themes.md): Provides guidance on designing and updating Grafana themes.
contribute/style-guides/documentation-style-guide.md
...@@ -4,14 +4,20 @@ This style guide applies to all documentation created for Grafana products. ...@@ -4,14 +4,20 @@ This style guide applies to all documentation created for Grafana products.
## Contributing ## 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 ## 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). 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 ## 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 ### General
* Use active voice. Avoid passive voice. * Use active voice. Avoid passive voice.
...@@ -81,7 +87,36 @@ When possible, use the exact title of the page or section you are linking to as ...@@ -81,7 +87,36 @@ When possible, use the exact title of the page or section you are linking to as
Grafana products has some words, abbreviations, and slang particular to this discourse community. Grafana products has some words, abbreviations, and slang particular to this discourse community.
#### data source
Two words, not one
**Exceptions:**
* "datasource" used as an identifier
* "datasource" in a URL
* "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*. * "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 a URL. * Use "data source" instead of "datasource" unless used as an identifier, in code, or as part of a URL.
* Spell out "repository" and avoid the shorter "repo." * Spell out "repository" and avoid the shorter "repo."
* Use "Unix" as the preferred spelling (as opposed to "UNIX", or "unix") when referring to the family of operating systems. * Use "Unix" as the preferred spelling (as opposed to "UNIX", or "unix") when referring to the family of operating systems.
#### 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.
**Examples**
* Set up the workspace.
* Initial setup might take five minutes.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment