Skip to content

Commit

Permalink
Docs: Clean up contribute docs (grafana#19716)
Browse files Browse the repository at this point in the history
  • Loading branch information
marcusolsson authored Oct 22, 2019
1 parent 9843a88 commit 73944c1
Show file tree
Hide file tree
Showing 9 changed files with 34 additions and 32 deletions.
11 changes: 2 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ If you believe you've found a security vulnerability, please read our [security

If you have an idea of how to improve Grafana, submit an [enhancement request](https://github.com/grafana/grafana/issues/new?labels=type%3A+feature+request&template=2-feature_request.md).

We want to make Grafana accessible to even more people. [Submit an accessibility issue](https://github.com/grafana/grafana/issues/new?labels=type%3A+accessibility&template=3-accessibility.md) to help us understand what we can improve.
We want to make Grafana accessible to even more people. Submit an [accessibility issue](https://github.com/grafana/grafana/issues/new?labels=type%3A+accessibility&template=3-accessibility.md) to help us understand what we can improve.

### Triage issues

Expand All @@ -54,19 +54,12 @@ Unsure where to begin contributing to Grafana? Start by browsing issues labeled

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).
When you're ready to contribute, it's time to [Create a pull request](/contribute/create-pull-request.md).

#### Contributor License Agreement (CLA)

Before we can accept your pull request, you need to [sign our CLA](https://grafana.com/docs/contribute/cla/). If you haven't, our CLA assistant prompts you to when you create your pull request.

## Community

- 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/).

## Where do I go from here?

- Set up your [development environment](contribute/developer-guide.md).
Expand Down
5 changes: 3 additions & 2 deletions ISSUE_TRIAGE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Triaging issues
# Triage issues

The main goal of issue triage is to categorize all incoming Grafana issues and make sure each issue has all basic information needed for anyone else to understand and be able to start working on it.

Expand All @@ -12,7 +12,8 @@ Triage helps ensure issues resolve quickly by:
* Giving a contributor the information they need before they commit to resolving an issue.
* Lowering the issue count by preventing duplicate issues.
* Streamlining the development process by preventing duplicate discussions.
* If you don't have the knowledge or time to code, consider helping with triage. The community will thank you for saving them time by spending some of yours.

If you don't have the knowledge or time to code, consider helping with triage. The community will thank you for saving them time by spending some of yours.

## Simplified flowchart diagram of the issue triage process

Expand Down
16 changes: 16 additions & 0 deletions contribute/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Contribute

This directory contains guides for contributors to the Grafana project.

- [Create a pull request](create-pull-request.md)
- [Contributing documentation](documentation.md)
- [Developer guide](developer-guide.md)
- [Triage issues](triage-issues.md)

The `style-guides` directory contains style guides for the Grafana software project and documentation.

- [Backend style guide](style-guides/backend.md) for how to style and format backend functionality and code.
- [Documentation style guide](style-guides/documentation-style-guide.md) for how to style and format documentation.
- [Frontend style guide](style-guides/frontend.md) for how to style and format the user-facing functionality and code.
- [Redux framework](style-guides/redux.md) for designing the Grafana redux framework.
- [Themes style guide](style-guides/themes.md) for designing and updating Grafana themes.
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ We're excited that you're considering making a contribution to the Grafana proje

We know you're excited to create your first pull request. Before we get started, read these resources first:

- Learn how to start [Contributing to Grafana](https://grafana.com/docs/contribute/overview/).
- Learn how to start [Contributing to Grafana](/CONTRIBUTING.md).
- Make sure your code follows the relevant [style guides](/contribute/style-guides).

## Your first pull request
Expand All @@ -30,16 +30,16 @@ If the pull request fixes a bug:

Pull requests for frontend contributions must:

- Use [Emotion](https://github.com/grafana/grafana/blob/master/style_guides/styling.md) for styling.
- Use [Emotion](/contribute/style-guides/styling.md) for styling.
- Not increase the Angular code base.
- Not use `any` or `{}` without reason.
- Not contain large React components that could easily be split into several smaller components.
- Not contain backend calls directly from components—use actions and Redux instead.

Pull requests for Redux contributions must:

- Use the `actionCreatorFactory` and `reducerFactory` helpers instead of traditional switch statement reducers in Redux. Refer to [Redux framework](https://github.com/grafana/grafana/tree/master/style_guides/redux.md) for more details.
- Use `reducerTester` to test reducers. Refer to [Redux framework](https://github.com/grafana/grafana/tree/master/style_guides/redux.md) for more details.
- Use the `actionCreatorFactory` and `reducerFactory` helpers instead of traditional switch statement reducers in Redux. Refer to [Redux framework](/contribute/style-guides/redux.md) for more details.
- Use `reducerTester` to test reducers. Refer to [Redux framework](/contribute/style-guides/redux.md) for more details.
- Not contain code that mutates state in reducers or thunks.
- Not contain code that accesses the reducers state slice directly. Instead, the code should use state selectors to access state.

Expand Down
9 changes: 5 additions & 4 deletions contribute/developer-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ app_mode = development

By now, you should be able to build and test a change you've made to the Grafana source code. In most cases, you need to add at least one data source to verify the change.

To set up data sources for your development environment, go to the [devenv](devenv) directory in the Grafana repository:
To set up data sources for your development environment, go to the [devenv](/devenv) directory in the Grafana repository:

```
cd devenv
Expand All @@ -149,7 +149,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](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`.
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. `prometheus_mac`.

## Build a Docker image

Expand Down Expand Up @@ -199,5 +199,6 @@ Another alternative is to limit the files being watched. The directories that ar
## Next steps

- Read our [style guides](/contribute/style-guides).
- Learn how to [Create a pull request](/contribute/pull-request.md).
- [Architecture](architecture).
- Learn how to [Create a pull request](/contribute/create-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).
- Read about the [architecture](architecture).
4 changes: 2 additions & 2 deletions contribute/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,13 @@ For general discussions on documentation, you’re welcome to join the `#docs` c

## 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](/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.

### Documentation structure

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](/docs/sources) directory. Subsections are added by creating a subdirectory in the directory of the parent section.

For each section, an `_index.md` file provides an overview of the topic.

Expand Down
9 changes: 0 additions & 9 deletions contribute/style-guides/README.md

This file was deleted.

2 changes: 1 addition & 1 deletion contribute/style-guides/backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ We enforce strict `gofmt` formatting and use some linters on our codebase. You c
$ make lint-go
```

We use [revive](https://github.com/mgechev/revive) as a go linter, and do enforce our [custom config](https://github.com/grafana/grafana/blob/master/conf/revive.toml) for it.
We use [revive](https://github.com/mgechev/revive) as a go linter, and do enforce our [custom config](/conf/revive.toml) for it.

The end goal is to follow the golint. And the approuch for reachin that goal is to lint all parts of the codebase that we are currently working on and enable stricter linting for more areas as we go.

Expand Down
2 changes: 1 addition & 1 deletion contribute/triage-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Investigate issues that we haven't been able to reproduce yet. In some cases, th

Use [GitHub reactions](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments) to let us know what's important to you. Vote on bugs if you've experienced the same problem. **Don't vote, or react, by commenting on the issue.**

Read more about [how we prioritize issues](https://github.com/grafana/grafana/blob/master/ISSUE_TRIAGE.md#4-prioritization-of-issues).
Read more about [how we prioritize issues](/ISSUE_TRIAGE.md#4-prioritization-of-issues).

## Report duplicates

Expand Down

0 comments on commit 73944c1

Please sign in to comment.