public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Improve guides for contributing (#19575)

Browse Source 
* Move style guides into contribute directory

* Move contribution guides into contribute directory

* Refactor CONTRIBUTING.md

* Clean up docs/README.md

* Update reference to style guide and minor formatting fixes

* Apply suggestions from code review

Co-Authored-By: gotjosh <josue.abreu@gmail.com>

* Update CONTRIBUTING.md

Co-Authored-By: gotjosh <josue.abreu@gmail.com>
This commit is contained in:
Marcus Olsson
2019-10-03 14:13:58 +02:00
committed by GitHub
co-authored by gotjosh
parent 27ddd2d60f
commit 2fb301ccaf
14 changed files with 189 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+17 -16
View File
@@ -6,14 +6,14 @@ The Markdown content however, is still public in this repository. We still encou
# Building the docs
To build the docs locally, you need to have docker installed. The docs are built using [Hugo](http://gohugo.io/) - a static site generator.
To build the docs locally, you need to have Docker installed. The docs are built using [Hugo](http://gohugo.io/) - a static site generator.
**Prepare the Docker Image**:
**Prepare the Docker image**:
> Due to migration to new static site, the docker image needs to be built from `old-docs` branch.
> Due to migration to new static site, the Docker image needs to be built from `old-docs` branch.
Git clone `grafana/website` repo. Run these commands in the root of that repo. **Note** that you may require ``sudo``
when running ``make docs-build`` depending on how your system's docker
Git clone `grafana/website` repo. Run these commands in the root of that repo. **Note** that you may require `sudo`
when running `make docs-build` depending on how your system's Docker
service is configured):
```
@@ -24,7 +24,7 @@ make docs-build
**Build the Documentation**:
Now that the docker image has been prepared we can build the
Now that the Docker image has been prepared we can build the
grafana docs and start a docs server.
If you have not cloned the Grafana repository already then:
@@ -47,14 +47,14 @@ An AWS config file is required to build the docs Docker image and to publish the
touch awsconfig
```
Then run (possibly with ``sudo``):
Then run (possibly with `sudo`):
```
make watch
```
This command will not return control of the shell to the user. Instead
the command is now running a new docker container built from the image
the command is now running a new Docker container built from the image
we created in the previous step.
Open [localhost:3004](http://localhost:3004) to view the docs.
@@ -63,20 +63,21 @@ Open [localhost:3004](http://localhost:3004) to view the docs.
All markdown files are part of [this repository](https://github.com/grafana/grafana). However, all images are added to the [website repository](https://github.com/grafana/website). Therefore, the process of adding images is not as straightforward. These are the steps:
1. Ensure you create a feature branch within the [website repository](https://github.com/grafana/website) to make the change. This branch needs to be based on the `old-docs` branch.
2. Ensure the image(s) are compressed and optimised e.g. Using [tinypng](https://tinypng.com/)
2. Add the image(s) to the `/static/img/docs` directory
3. Then, make a commit that adds the image(s)
4. The Pull Request you create needs to target where you branched off, the branch `old-docs`
1. Ensure you create a feature branch within the [website repository](https://github.com/grafana/website) to make the change. This branch needs to be based on the `old-docs` branch.
1. Ensure the image(s) are compressed and optimised e.g. Using [tinypng](https://tinypng.com/).
1. Add the image(s) to the `/static/img/docs` directory.
1. Then, make a commit that adds the image(s).
1. The Pull Request you create needs to target where you branched off, the branch `old-docs`.
Finally, run:
```
make docs-build
```
This will rebuild the docs docker image.
This will rebuild the docs Docker image.
To be able to use your image(s) you have to quit (CTRL-C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image(s).
To be able to use your image(s) you have to quit (CTRL-C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image(s).
### Editing content
@@ -86,4 +87,4 @@ Changes to the markdown files should automatically cause a docs rebuild and live
#### Running `make watch` errors out with `Warning: Task "default" not found.`
Ensure that the docker image from the [website repository](https://github.com/grafana/website) is built using the `old-docs` branch.
Ensure that the Docker image from the [website repository](https://github.com/grafana/website) is built using the `old-docs` branch.
docs/sources/contribute/development/_index.md
-11
View File
@@ -1,11 +0,0 @@
+++
title = "Development"
type = "docs"
[menu.docs]
name = "Development"
identifier = "development"
parent = "contribute"
weight = 2
+++
# Development
docs/sources/contribute/development/developing-on-macos.md
-119
View File
@@ -1,119 +0,0 @@
+++
title = "Developing on macOS"
description = "Developing on macOS"
type = "docs"
[menu.docs]
parent = "development"
weight = 1
+++
# Developing on macOS
This guide helps you get started developing Grafana on macOS.
## Dependencies
Make sure you have the following dependencies installed before moving on to set up your developer environment:
- [Git](https://git-scm.com/)
- [Go](https://golang.org/dl/)
- [Node.js (Long Term Support)](https://nodejs.org)
- [Yarn](https://yarnpkg.com)
We recommend using [Homebrew](https://brew.sh/) for installing any missing dependencies:
```
brew install git
brew install go
brew install node
npm install -g yarn
```
## Download Grafana
We recommend using Go to download the source code for the Grafana project:
1. Add `export GOPATH=$HOME/go/` to the bottom of your `$HOME/.bash_profile`.
1. Open a terminal and run `go get github.com/grafana/` in your terminal. This command downloads, and installs Grafana to your `$GOPATH`.
1. Open `$GOPATH/src/github.com/grafana/grafana` in your favorite code editor.
## Build Grafana
Grafana consists of two components; the _frontend_, and the _backend_.
### Frontend
Before we can build the frontend assets, we need to install the dependencies:
```
yarn install --pure-lockfile
```
When this is done, 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.
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.
By default, the web server will be served at `http://localhost:3000/`.
Log in using the default credentials:
| username | password |
|----------|----------|
| `admin` | `admin` |
When you log in for the first time, you'll be asked to change your password.
## Test Grafana
The tests for the frontend are written using [jest](https://jestjs.io/). Run them using yarn:
```
yarn jest
```
If you're developing for the backend, run the tests with the standard Go tool:
```
go test -v ./pkg/...
```
## Add data sources
By now, you should be able to build and test a change you've made to the Grafana source code. Most likely though, you're going to need to add a few data sources to verify the change you made.
To set up data sources for your development environment, go to the `devenv` directory in the Grafana repository:
```
cd devenv
```
Run the `setup.sh` script to setup a set of data sources and dashboards in your local Grafana. Data sources are named **gdev-\<type\>**, and dashboards are located in a folder called **gdev dashboards**.
Some of the data sources require databases to run in the background.
Installing and configuring databases can be a tricky business. Grafana uses [Docker](https://docker.com) to make the task of setting up databases a little easier. Make sure you [install Docker](https://docs.docker.com/docker-for-mac/install/) before proceeding to the next step.
In the root directory of your Grafana repository, run the following command:
```
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](https://github.com/grafana/grafana/tree/master/devenv/docker/blocks). Note that some data sources have specific Docker images for macOS, e.g. `prometheus_mac`.
## Learn more
- [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).
docs/sources/contribute/documentation.md
-51
View File
@@ -1,51 +0,0 @@
+++
title = "Documentation"
description = "Contributing to documentation"
type = "docs"
[menu.docs]
parent = "contribute"
weight = 2
+++
# Contributing to documentation
## How do I contribute?
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.
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.
If you encounter any misspellings, or violations to the style guide, please let us know by submitting an issue.
On every page in the documentation there are two links:
- __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
If you have questions on a specific issue, post a comment to ask for clarification, or to give feedback.
For general discussions on documentation, you’re welcome to join the `#docs` channel on our [public Grafana Slack](http://slack.raintank.io) team.
## Guidelines
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
The documentation is organized into topics, called _sections_.
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.
### 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.