Docs: Improve guides for contributing (#19575)
* 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
gotjosh
@@ -0,0 +1,114 @@
|
||||
# Develop Grafana
|
||||
|
||||
This guide helps you get started developing Grafana.
|
||||
|
||||
## 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)
|
||||
|
||||
### macOS
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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, you can access the web server at `http://localhost:3000/`.
|
||||
|
||||
Log in using the default credentials:
|
||||
|
||||
| username | password |
|
||||
| -------- | -------- |
|
||||
| `admin` | `admin` |
|
||||
|
||||
When you log in for the first time, Grafana will ask you to change your password.
|
||||
|
||||
## Test Grafana
|
||||
|
||||
We use [jest](https://jestjs.io/) for our frontend tests. 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. 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` 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. 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.
|
||||
|
||||
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
|
||||
|
||||
- Read our [style guides](/contribute/style-guides).
|
||||
- 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).
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to documentation
|
||||
|
||||
This documents guides you through the process of contributing to the Grafana documentation. Make sure you've read the guide for [Contributing to Grafana](/CONTRIBUTING.md).
|
||||
|
||||
## Your first contribution
|
||||
|
||||
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](https://grafana.com/docs/) 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
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,94 @@
|
||||
# Create a pull request
|
||||
|
||||
We're excited that you're considering making a contribution to the Grafana project! This document guides you through the process of creating a [pull request](https://help.github.com/en/articles/about-pull-requests/).
|
||||
|
||||
## Before you begin
|
||||
|
||||
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/).
|
||||
- Make sure your code follows the relevant [style guides](/contribute/style-guides).
|
||||
|
||||
## Your first pull request
|
||||
|
||||
If this is your first time contributing to an open-source project on GitHub, make sure you read about [Creating a pull request](https://help.github.com/en/articles/creating-a-pull-request).
|
||||
|
||||
To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines:
|
||||
|
||||
- Title and description matches the implementation.
|
||||
- Commits within the pull request follow the [style guide](#style-guide).
|
||||
- The pull request closes one related issue.
|
||||
- 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 the pull request fixes a bug:
|
||||
|
||||
- The pull request description must include `Closes #<issue number>` or `Fixes #<issue number>`.
|
||||
- To avoid regressions, the pull request should include tests that replicate the fixed bug.
|
||||
|
||||
### Frontend-specific guidelines
|
||||
|
||||
Pull requests for frontend contributions must:
|
||||
|
||||
- Use [Emotion](https://github.com/grafana/grafana/blob/master/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.
|
||||
- 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.
|
||||
|
||||
## Code review
|
||||
|
||||
Once you've created a pull request, the next step is to have someone review your change. A review is a learning opportunity for both the reviewer and the author of the pull request.
|
||||
|
||||
If you think a specific person needs to review your pull request, then you can tag them in the description or in a comment. Tag a user by typing the `@` symbol followed by their GitHub username.
|
||||
|
||||
We recommend that you read [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) to learn more about code reviews.
|
||||
|
||||
## Formatting guidelines
|
||||
|
||||
A well-written pull request minimizes the time to get your change accepted. These guidelines help you write good commit messages and descriptions for your pull requests.
|
||||
|
||||
### Commit message format
|
||||
|
||||
Grafana uses the guidelines for commit messages outlined in [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/), with the following additions:
|
||||
|
||||
- Subject line must begin with the _area_ of the commit.
|
||||
- A footer in the form of an optional [keyword and issue reference](https://help.github.com/en/articles/closing-issues-using-keywords).
|
||||
|
||||
#### Area
|
||||
|
||||
The area should use upper camel case, e.g. UpperCamelCase.
|
||||
|
||||
Prefer using one of the following areas:
|
||||
|
||||
- **Build:** Changes to the build system, or external dependencies.
|
||||
- **Chore:** Changes that don't affect functionality.
|
||||
- **Dashboard:** Changes to the Dashboard feature.
|
||||
- **Docs:** Changes to documentation.
|
||||
- **Explore:** Changes to the Explore feature.
|
||||
- **Plugins:** Changes to any of the plugins.
|
||||
|
||||
For changes to data sources, the area should be the name of the data source, e.g., AzureMonitor, Graphite, and Prometheus.
|
||||
|
||||
For changes to panels, the area should be the name of the panel, suffixed with Panel, e.g., GraphPanel, SinglestatPanel, and TablePanel.
|
||||
|
||||
**Example**
|
||||
|
||||
- `Build: Support publishing MSI to grafana.com`
|
||||
- `Explore: Add Live option for supported data sources`
|
||||
- `GraphPanel: Fix legend sorting issues`
|
||||
|
||||
### Pull request titles
|
||||
|
||||
The Grafana team _squashes_ all commits into one when we accept a pull request. The title of the pull request becomes the subject line of the squashed commit message. We still encourage contributors to write informative commit messages, as they becomes a part of the Git commit body.
|
||||
|
||||
We use the pull request title when we generate change logs for releases. As such, we strive to make the title as informative as possible.
|
||||
|
||||
Make sure that the title for your pull request uses the same format as the subject line in the commit message.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Style guides
|
||||
|
||||
This section contains style guides for the Grafana software project and documentation.
|
||||
|
||||
- [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.
|
||||
- [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.
|
||||
- [Themes style guide](themes.md): Provides guidance on designing and updating Grafana themes.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Backend style guide
|
||||
|
||||
Grafanas backend has been developed for a long time with a mix of code styles.
|
||||
|
||||
This style guide is a guide for how we want to write Go code in the future. Generally, we want to follow the style guides used in Go [Code Review Comments](https://code.google.com/p/go-wiki/wiki/CodeReviewComments) and Peter Bourgon's [Go: Best Practices for Production Environments](http://peter.bourgon.org/go-in-production/#formatting-and-style)
|
||||
|
||||
## Linting and formatting
|
||||
We enforce strict `gofmt` formatting and use some linters on our codebase. You can lint the codebase with <akefile -
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
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.
|
||||
|
||||
## Testing
|
||||
We use GoConvey for BDD/scenario based testing. Which we think is useful for testing certain chain or interactions. Ex https://github.com/grafana/grafana/blob/master/pkg/services/auth/auth_token_test.go
|
||||
|
||||
We value clean & readable code that is loosely coupled and covered by unit tests. This makes it easier to collaborate and maintain the code. In the sqlstore package we do database operations in tests and while some might say that's not suited for unit tests. We think they are fast enough and provide a lot of value.
|
||||
|
||||
For new tests its preferred to use standard library testing.
|
||||
|
||||
### Mocks/Stubs
|
||||
As a general rule of thumb we try to override/replace functions/methods when mocks/stubs are needed. One common task is the need of overriding time (`time.Now()`). See usage of `getTime` variable in [code](https://github.com/grafana/grafana/blob/52c39904120fb0b98494b961be67bb47574245b1/pkg/services/auth/auth_token.go#L22) and in [test](https://github.com/grafana/grafana/blob/52c39904120fb0b98494b961be67bb47574245b1/pkg/services/auth/auth_token_test.go#L23-L26) as an example.
|
||||
|
||||
When you need to stub/mock an interface you can implement a struct that allows you to override methods on a test-by-test basis. See [stub](https://github.com/grafana/grafana/blob/52c39904120fb0b98494b961be67bb47574245b1/pkg/services/auth/testing.go) and [example usage](https://github.com/grafana/grafana/blob/52c39904120fb0b98494b961be67bb47574245b1/pkg/middleware/middleware_test.go#L153-L180).
|
||||
@@ -0,0 +1,70 @@
|
||||
# Documentation style guide
|
||||
|
||||
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.
|
||||
|
||||
## 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).
|
||||
|
||||
## Grafana-specific style
|
||||
|
||||
### General
|
||||
|
||||
* Use active voice. Avoid passive voice.
|
||||
- Passive: The heatmap visualization is displayed.
|
||||
- Active: Grafana displays the heatmap visualization.
|
||||
* Write in the imperative second person. Examples: You can write a query. Click the panel. Close the window.
|
||||
* Write in present tense.
|
||||
- Not: The panel will open.
|
||||
- Use: The panel opens. Grafana opens the panel.
|
||||
* Do not use an ampersand (&) as an abbreviation for "and."
|
||||
- **Exceptions:** If an ampersand is used in the Grafana UI, then match the UI.
|
||||
|
||||
### File naming conventions
|
||||
|
||||
- Files that are displayed in the help system should have names that are all lowercase, no spaces. Use hyphens instead of spaces. Example: glossary.md
|
||||
- Documentation file names should match the title. **Note:** This only applies to new files at this time. Do not change the names of older files unless directed to do so.
|
||||
- Internal reference file names should be all uppercase except the file extension. Example: CONTRIBUTING.md
|
||||
|
||||
### Headings
|
||||
|
||||
* Write headings in sentence case, not title case.
|
||||
- This is sentence case
|
||||
- This Is Title Case
|
||||
* Task topic headings start with a verb.
|
||||
- Write a query. Create a dashboard.
|
||||
* Concept and reference topic headings should be nouns or gerunds. Examples: Contributing to docs, Visualizations, Style guide
|
||||
* Avoid following one heading with another heading.
|
||||
* Avoid skipping heading levels. For example, an h1 should be followed by an h2 rather than an h3.
|
||||
* Avoid having just one lower-level heading. For example, h1, h2, h2, h3, h3, h2 is a good order. Do no go h1, h2, h3, h2, h3, h2.
|
||||
|
||||
### Images
|
||||
|
||||
* Preferred format is .png
|
||||
* File extension should be all lowercase.
|
||||
* Preferred DPI is 72.
|
||||
* Assume all graphics will be exclusively viewed on the web.
|
||||
* Maximum image size is 3840px X 2160px.
|
||||
* Screenshots should be readable, but not too large.
|
||||
|
||||
### Capitalization
|
||||
|
||||
* Grafana, Loki, and Prometheus are always capitalized unless part of a code block.
|
||||
* Git is always capitalized, unless part of a code block.
|
||||
* Abbreviations are always capitalized (such as HTTP or URL)
|
||||
|
||||
### Word usage
|
||||
|
||||
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
|
||||
@@ -0,0 +1,93 @@
|
||||
# Frontend Style Guide
|
||||
|
||||
Generally we follow the Airbnb [React Style Guide](https://github.com/airbnb/javascript/tree/master/react).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Frontend Style Guide](#frontend-style-guide)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Basic rules](#basic-rules)
|
||||
- [Organization](#organization)
|
||||
- [Props](#props)
|
||||
- [State management](#state-management)
|
||||
|
||||
## Basic rules
|
||||
|
||||
- Try to keep files small and focused.
|
||||
- Break large components up into sub-components.
|
||||
|
||||
## Organization
|
||||
|
||||
- Components and types that needs to be used by external plugins needs to go into @grafana/ui
|
||||
- Components should get their own folder under features/xxx/components
|
||||
- Sub components can live in that component folders, so small component do not need their own folder
|
||||
- Place test next to their component file (same dir)
|
||||
- Component sass should live in the same folder as component code
|
||||
- State logic & domain models should live in features/xxx/state
|
||||
- Containers (pages) can live in feature root features/xxx
|
||||
- up for debate?
|
||||
|
||||
## Props
|
||||
|
||||
- Name callback props and handlers with an "on" prefix.
|
||||
|
||||
```tsx
|
||||
// good
|
||||
onChange = () => {
|
||||
|
||||
};
|
||||
|
||||
render() {
|
||||
return (
|
||||
<MyComponent onChange={this.onChange} />
|
||||
);
|
||||
}
|
||||
|
||||
// bad
|
||||
handleChange = () => {
|
||||
|
||||
};
|
||||
|
||||
render() {
|
||||
return (
|
||||
<MyComponent changed={this.handleChange} />
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
- React Component definitions
|
||||
|
||||
```jsx
|
||||
// good
|
||||
export class YourClass extends PureComponent<{},{}> { ... }
|
||||
|
||||
// bad
|
||||
export class YourClass extends PureComponent { ... }
|
||||
```
|
||||
|
||||
- React Component constructor
|
||||
|
||||
```typescript
|
||||
// good
|
||||
constructor(props:Props) {...}
|
||||
|
||||
// bad
|
||||
constructor(props) {...}
|
||||
```
|
||||
|
||||
- React Component defaultProps
|
||||
|
||||
```typescript
|
||||
// good
|
||||
static defaultProps: Partial<Props> = { ... }
|
||||
|
||||
// bad
|
||||
static defaultProps = { ... }
|
||||
```
|
||||
|
||||
## State management
|
||||
|
||||
- Don't mutate state in reducers or thunks.
|
||||
- Use helpers `actionCreatorFactory` and `reducerFactory` instead of traditional `switch statement` reducers in Redux. See [Redux framework](redux.md) for more details.
|
||||
- Use `reducerTester` to test reducers. See [Redux framework](redux.md) for more details.
|
||||
- Use state selectors to access state instead of accessing state directly.
|
||||
@@ -0,0 +1,133 @@
|
||||
# Redux framework
|
||||
|
||||
To reduce the amount of boilerplate code used to create a strongly typed redux solution with actions, action creators, reducers and tests we've introduced a small framework around Redux.
|
||||
|
||||
`+` Much less boilerplate code
|
||||
`-` Non Redux standard api
|
||||
|
||||
## New core functionality
|
||||
|
||||
### actionCreatorFactory
|
||||
|
||||
Used to create an action creator with the following signature
|
||||
|
||||
```typescript
|
||||
{ type: string , (payload: T): {type: string; payload: T;} }
|
||||
```
|
||||
|
||||
where the `type` string will be ensured to be unique and `T` is the type supplied to the factory.
|
||||
|
||||
#### Example
|
||||
|
||||
```typescript
|
||||
export const someAction = actionCreatorFactory<string>('SOME_ACTION').create();
|
||||
|
||||
// later when dispatched
|
||||
someAction('this rocks!');
|
||||
```
|
||||
|
||||
```typescript
|
||||
// best practices, always use an interface as type
|
||||
interface SomeAction {
|
||||
data: string;
|
||||
}
|
||||
export const someAction = actionCreatorFactory<SomeAction>('SOME_ACTION').create();
|
||||
|
||||
// later when dispatched
|
||||
someAction({ data: 'best practices' });
|
||||
```
|
||||
|
||||
```typescript
|
||||
// declaring an action creator with a type string that has already been defined will throw
|
||||
export const someAction = actionCreatorFactory<string>('SOME_ACTION').create();
|
||||
export const theAction = actionCreatorFactory<string>('SOME_ACTION').create(); // will throw
|
||||
```
|
||||
|
||||
### reducerFactory
|
||||
|
||||
Fluent API used to create a reducer. (same as implementing the standard switch statement in Redux)
|
||||
|
||||
#### Example
|
||||
|
||||
```typescript
|
||||
interface ExampleReducerState {
|
||||
data: string[];
|
||||
}
|
||||
|
||||
const intialState: ExampleReducerState = { data: [] };
|
||||
|
||||
export const someAction = actionCreatorFactory<string>('SOME_ACTION').create();
|
||||
export const otherAction = actionCreatorFactory<string[]>('Other_ACTION').create();
|
||||
|
||||
export const exampleReducer = reducerFactory<ExampleReducerState>(intialState)
|
||||
// addMapper is the function that ties an action creator to a state change
|
||||
.addMapper({
|
||||
// action creator to filter out which mapper to use
|
||||
filter: someAction,
|
||||
// mapper function where the state change occurs
|
||||
mapper: (state, action) => ({ ...state, data: state.data.concat(action.payload) }),
|
||||
})
|
||||
// a developer can just chain addMapper functions until reducer is done
|
||||
.addMapper({
|
||||
filter: otherAction,
|
||||
mapper: (state, action) => ({ ...state, data: action.payload }),
|
||||
})
|
||||
.create(); // this will return the reducer
|
||||
```
|
||||
|
||||
#### Typing limitations
|
||||
|
||||
There is a challenge left with the mapper function that I can not solve with TypeScript. The signature of a mapper is
|
||||
|
||||
```typescript
|
||||
<State, Payload>(state: State, action: ActionOf<Payload>) => State;
|
||||
```
|
||||
|
||||
If you would to return an object that is not of the state type like the following mapper
|
||||
|
||||
```typescript
|
||||
mapper: (state, action) => ({ nonExistingProperty: ''}),
|
||||
```
|
||||
|
||||
Then you would receive the following compile error
|
||||
|
||||
```shell
|
||||
[ts] Property 'data' is missing in type '{ nonExistingProperty: string; }' but required in type 'ExampleReducerState'. [2741]
|
||||
```
|
||||
|
||||
But if you return an object that is spreading state and add a non existing property type like the following mapper
|
||||
|
||||
```typescript
|
||||
mapper: (state, action) => ({ ...state, nonExistingProperty: ''}),
|
||||
```
|
||||
|
||||
Then you would not receive any compile error.
|
||||
|
||||
If you want to make sure that never happens you can just supply the State type to the mapper callback like the following mapper:
|
||||
|
||||
```typescript
|
||||
mapper: (state, action): ExampleReducerState => ({ ...state, nonExistingProperty: 'kalle' }),
|
||||
```
|
||||
|
||||
Then you would receive the following compile error
|
||||
|
||||
```shell
|
||||
[ts]
|
||||
Type '{ nonExistingProperty: string; data: string[]; }' is not assignable to type 'ExampleReducerState'.
|
||||
Object literal may only specify known properties, and 'nonExistingProperty' does not exist in type 'ExampleReducerState'. [2322]
|
||||
```
|
||||
|
||||
## New test functionality
|
||||
|
||||
### reducerTester
|
||||
|
||||
Fluent API that simplifies the testing of reducers
|
||||
|
||||
#### Example
|
||||
|
||||
```typescript
|
||||
reducerTester()
|
||||
.givenReducer(someReducer, initialState)
|
||||
.whenActionIsDispatched(someAction('reducer tests'))
|
||||
.thenStateShouldEqual({ ...initialState, data: 'reducer tests' });
|
||||
```
|
||||
@@ -0,0 +1,84 @@
|
||||
# Styling Grafana
|
||||
|
||||
## Emotion
|
||||
|
||||
[Emotion](https://emotion.sh/docs/introduction) is our default-to-be approach to styling React components. It provides a way for styles to be a consequence of properties and state of a component.
|
||||
|
||||
### Usage
|
||||
|
||||
#### Basic styling
|
||||
|
||||
For styling components use Emotion's `css` function
|
||||
|
||||
```tsx
|
||||
import { css } from 'emotion';
|
||||
|
||||
|
||||
const ComponentA = () => {
|
||||
return (
|
||||
<div className={css`background: red;`}>
|
||||
As red as you can ge
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Styling complex components
|
||||
|
||||
In more complex cases, especially when you need to style multiple DOM elements in one component or when your styles that depend on properties and/or state, you should create a helper function that returns an object with desired stylesheet. Let's say you need to style a component that has different background depending on the theme:
|
||||
|
||||
```tsx
|
||||
import { css, cx } from 'emotion';
|
||||
import { GrafanaTheme, useTheme, selectThemeVariant } from '@grafana/ui';
|
||||
|
||||
const getStyles = (theme: GrafanaTheme) => {
|
||||
const backgroundColor = selectThemeVariant({ light: theme.colors.red, dark: theme.colors.blue }, theme.type);
|
||||
|
||||
return {
|
||||
wrapper: css`
|
||||
background: ${backgroundColor};
|
||||
`,
|
||||
icon: css`font-size:${theme.typography.size.sm}`;
|
||||
};
|
||||
}
|
||||
|
||||
const ComponentA = () => {
|
||||
const theme = useTheme();
|
||||
const styles = getStyles(theme);
|
||||
|
||||
return (
|
||||
<div className={styles.wrapper}>
|
||||
As red as you can ge
|
||||
<i className={styles.icon} /\>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
For more information about themes at Grafana please see [themes guide](./themes.md)
|
||||
|
||||
#### Composing class names
|
||||
|
||||
For class composition use Emotion's `cx` function
|
||||
|
||||
```tsx
|
||||
import { css, cx } from 'emotion';
|
||||
|
||||
|
||||
interface Props {
|
||||
className?: string;
|
||||
}
|
||||
|
||||
const ComponentA: React.FC<Props> = ({ className }) => {
|
||||
const finalClassName = cx(
|
||||
className,
|
||||
css`background: red`,
|
||||
)
|
||||
|
||||
return (
|
||||
<div className={finalClassName}>
|
||||
As red as you can ge
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,107 @@
|
||||
# Theming Grafana
|
||||
|
||||
## Overview
|
||||
|
||||
**Themes are implemented in Typescript.** That's because our goal is to share variables between Grafana Typescript code and SASS files. Theme definitions are located in `packages/grafana-ui/src/themes/[default|dark|light].ts` files. `default.ts` file holds common variables like typography and spacing definitions, while `[light|dark].ts` primarily specify colors used in themes.
|
||||
|
||||
## Usage
|
||||
### Using themes in React components
|
||||
|
||||
#### Using `ThemeContext` directly
|
||||
|
||||
```tsx
|
||||
import { ThemeContext } from '@grafana/ui';
|
||||
|
||||
<ThemeContext.Consumer>{theme => <Foo theme={theme} />}</ThemeContext.Consumer>;
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```tsx
|
||||
import React, { useContext } from 'react';
|
||||
import { ThemeContext } from '@grafana/ui';
|
||||
|
||||
const Foo: React.FunctionComponent<FooProps> = () => {
|
||||
const theme = useContext(ThemeContext);
|
||||
|
||||
// Your component has access to the theme variables now
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
#### Using `withTheme` HOC
|
||||
|
||||
With this method your component will be automatically wrapped in `ThemeContext.Consumer` and provided with current theme via `theme` prop. Component used with `withTheme` must implement `Themeable` interface.
|
||||
|
||||
```ts
|
||||
import { ThemeContext, Themeable } from '@grafana/ui';
|
||||
|
||||
interface FooProps extends Themeable {}
|
||||
|
||||
const Foo: React.FunctionComponent<FooProps> = () => ...
|
||||
|
||||
export default withTheme(Foo);
|
||||
```
|
||||
|
||||
### Using themes in Storybook
|
||||
|
||||
All stories are wrapped with `ThemeContext.Provider` using global decorator. To render `Themeable` component that's not wrapped by `withTheme` HOC you either create a new component in your story:
|
||||
|
||||
```tsx
|
||||
// Foo.story.tsx
|
||||
const FooWithTheme = withTheme(Foo);
|
||||
|
||||
FooStories.add('Story' () => {
|
||||
return <FooWithTheme />
|
||||
});
|
||||
```
|
||||
|
||||
or use `renderComponentWithTheme` helper:
|
||||
|
||||
```tsx
|
||||
// Bar.story.tsx
|
||||
|
||||
BarStories.add('Story' () => {
|
||||
return renderComponentWithTheme(Bar, /* pass props here */)
|
||||
});
|
||||
```
|
||||
|
||||
### Using themes in Angular code
|
||||
|
||||
There should be very few cases where theme would be used in Angular context. For this purpose there is a function available that retrieves current theme: `import { getCurrentTheme } from app/core/utils/ConfigProvider`. Angular components should be migrated to React, or if that's not possible at the moment, styled using SASS.
|
||||
|
||||
|
||||
## FAQ
|
||||
### How can I modify SASS variable files?
|
||||
> For the following to apply you need to run `yarn dev` task.
|
||||
|
||||
`[_variables|_variables.dark|_variables.light].generated.scss` files are the ones that are referenced in the main SASS files for SASS variables to be available. **These files are automatically generated and should never be modified by hand!**.
|
||||
|
||||
#### If you need to modify *SASS variable value* you need to modify corresponding Typescript file that is a source of the variables:
|
||||
- `_variables.generated.scss` - modify `grafana-ui/src/themes/default.ts`
|
||||
- `_variables.light.generated.scss` - modify `grafana-ui/src/themes/light.ts`
|
||||
- `_variables.dark.generated.scss` - modify `grafana-ui/src/themes/dark.ts`
|
||||
|
||||
#### If you need to *add new variable* to SASS variables you need to modify corresponding template file:
|
||||
- `_variables.generated.scss` - modify `grafana-ui/src/themes/_variables.scss.tmpl.ts`
|
||||
- `_variables.light.generated.scss` - modify `grafana-ui/src/themes/_variables.light.scss.tmpl.ts`
|
||||
- `_variables.dark.generated.scss` - modify `grafana-ui/src/themes/_variables.dark.scss.tmpl.ts`
|
||||
|
||||
|
||||
## Limitations
|
||||
### You must ensure ThemeContext provider is available in a React tree
|
||||
By default all react2angular directives have `ThemeContext.Provider` ensured. But, there are cases where we create another React tree via `ReactDOM.render`. This happens in case of graph legend rendering and `ReactContainer` directive. In such cases theme consumption will fail. To make sure theme context is available in such cases, you need to wrap your rendered component with ThemeContext.Provider using `provideTheme` function:
|
||||
|
||||
```ts
|
||||
// graph.ts
|
||||
import { provideTheme } from 'app/core/utils/ConfigProvider';
|
||||
|
||||
// Create component with ThemeContext.Provider first.
|
||||
// Otherwise React will create new components every time it renders!
|
||||
const LegendWithThemeProvider = provideTheme(Legend);
|
||||
|
||||
const legendReactElem = React.createElement(LegendWithThemeProvider, legendProps);
|
||||
ReactDOM.render(legendReactElem, this.legendElem, () => this.renderPanel());
|
||||
```
|
||||
|
||||
`provideTheme` makes current theme available via ThemeContext by checking if user has `lightTheme` set in her boot data.
|
||||
Reference in New Issue
Block a user