If you're looking for ideas on what to contribute, in addition to taking a look at issues with the `help-wanted` tag, you may also want to view the [Dashboard roadmap](../common/roadmap.md).
If you have any further questions, feel free to ask in `#sig-ui` on the [Kubernetes' Slack](https://kubernetes.slack.com/).
We are following conventions described in [Effective Go](https://golang.org/doc/effective_go.html) document.
Go to our [Go Report Card](https://goreportcard.com/report/github.com/kubernetes/dashboard) to check how well we are doing.
## Frontend
We are following conventions described in [Angular Style Guide](https://angular.io/guide/styleguide) and [Material Design Guidelines](https://material.io/guidelines/).
Additionally, check the list of rules and tips, that we are using:
* Private method and variable names should end with a `_`.
* In order to keep all tooltips consistent across whole application, we have decided to use 500 ms delay and auto-hide option. It allows us to avoid flickering when moving the mouse over the pages and to hide tooltips after the mouse is elsewhere but the focus is still on the element with tooltip.
An overview of the features provided by the dashboard can be found [here](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard).
## Code style check and formatting
The code style check suite includes format checks can be executed with:
```
npm run check
```
The code formatting can be executed with:
```
npm run fix
```
These check and formatting involves in go, ts, scss, html, license and i18n files.
We use following tools and settings for each check and formatting:
Clone the repository into `$GOPATH/src/github.com/kubernetes/dashboard` and install the dependencies:
```
npm ci
```
If you are running commands with root privileges set `--unsafe-perm flag`:
```
npm ci --unsafe-perm
```
## Running the cluster
To make Dashboard work you need to have cluster running. If you would like to use local cluster we recommend [kubeadm](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/), [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) or [kubeadm-dind-cluster](https://github.com/Mirantis/kubeadm-dind-cluster). The most convenient way is to make it work is to create a proxy. Run the following command:
```
kubectl proxy
```
kubectl will handle authentication with Kubernetes and create an API proxy with the address `localhost:8080`. Therefore, no changes in the configuration are required.
Another way to connect to real cluster while developing dashboard is to override default values used by our build pipeline. In order to do that we have introduced two environment variables `KUBE_DASHBOARD_APISERVER_HOST` and `KUBE_DASHBOARD_KUBECONFIG` that will be used over default ones when defined. Before running our npm tasks just do:
**NOTE: Environment variable `KUBE_DASHBOARD_KUBECONFIG` has higher priority than `KUBE_DASHBOARD_APISERVER_HOST`.**
## Serving Dashboard for Development
Quick updated version:
```
npm start
```
Open a browser and access the UI under `localhost:8080`.
In the background, `npm start` makes a [concurrently](https://github.com/kimmobrunfeldt/concurrently#readme) call to start the `golang` backend server and the `angular` development server.
Once the angular server starts, it takes some time to pre-compile all assets before serving them. By default, the angular development server watches for file changes and will update accordingly.
## Building Dashboard for production
The Dashboard project can be built for production by using the following task:
```
npm run build
```
The code is compiled, compressed and debug support removed. The dashboard binary can be found in the `dist` folder.
To build and immediately serve Dashboard from the `dist` folder, use the following task:
```
npm run start:prod
```
Open a browser and access the UI under `localhost:9090`. The following processes should be running (respective ports are given in parentheses):
`Dashboard backend (9090) ---> Kubernetes API server (8080)`
In order to package everything into a ready-to-run Docker image, use the following task:
```
npm run docker:build:head
```
You might notice that the Docker image is very small and requires only a few MB. Only Dashboard assets are added to a scratch image. This is possible, because the `dashboard` binary has no external dependencies. Awesome!
## Run the tests
Unit tests should be executed after every source code change. The following task makes this a breeze. The full test suite includes unit tests and integration tests.
```
npm run test
```
You can also run individual tests on their own (such as the backend or frontend tests) by doing the following:
```
npm run test:frontend
```
or
```
npm run test:backend
```
The code style check suite includes format checks can be executed with:
```
npm run check
```
The code formatting can be executed with:
```
npm run fix
```
These check and formatting involves in go, ts, scss, html, license and i18n files.
## Committing changes to your fork
Before committing any changes, please run `npm run check`. This will keep you from accidentally committing non tested and unformatted code.
Since the hooks for commit has been set with `husky` into `<dashboard_home>/.git/hooks/pre-commit` already if you installed dashboard according to above, so it will run `npm run fix` and keep your code as formatted.
Then you can commit your changes and push them to your fork:
```
git commit
git push -f origin my-feature
```
## Easy way to build your development environment with Docker
At first, change directory to kubernetes dashboard repository of your fork.
### Allow accessing dashboard from outside the container
Development container runs Kubernetes Dashboard in insecure mode by default,
but Kubernetes Dashboard is not exposed to outside the container in insecure
mode by default.
To allow accessing dashboard from outside the development container,
pass value for `--insecure-bind-address` option to dashboard as follows:
* Set `K8S_DASHBOARD_BIND_ADDRESS` environment variable as `"0.0.0.0"` before using `aio/develop/run-npm-on-container.sh`.
* Run like `npm run [command] --kubernetes-dashboard:bind_address="0.0.0.0"`, when you run dashboard from inside the container.
### To run dashboard using Docker at ease
1. Run `aio/develop/run-npm-on-container.sh`.
That's all. It will build dashboard container from your local repository, will create also kubernetes cluster container for your dashboard using [`kind`](https://github.com/kubernetes-sigs/kind), and will run dashboard.
Then you can see dashboard `http://localhost:8080` with your browser.
### To run with your another Kubernetes cluster
1. Copy kubeconfig from your cluster, and confirm the URL for API server in it, and modify it if necessary.
2. Set filepath for kubeconfig into `K8S_DASHBOARD_KUBECONFIG` environment variable.
3. Change directory into your dashboard source directory.
4. Run `aio/develop/run-npm-on-container.sh`.
These manipulations will build container, and run dashboard as default.
### To run npm commands as you want
Also, you can run npm commands described in package.json as you want
e.g.
1. To test dashboard, run `aio/develop/run-npm-on-container.sh run test`.
2. To check your code changes, run `aio/develop/run-npm-on-container.sh run check`.
This container create `user` with `UID` and `GID` same as local user, switch user to `user` with `gosu` and run commands. So created or updated files like results of `npm run fix` or `npm run build` would have same ownership as your host. You can commit them immediately from your host.
### To run container without creating cluster and running dashboard
1. Set `K8S_DASHBOARD_CMD` environment variable as `bash`.
2. Run `aio/develop/run-npm-on-container.sh`.
3. Run commands as you like in the container.
This runs container with `bash` command.
### To access console inside of running development container
1. Run `docker exec -it k8s-dashboard-dev gosu user bash`.
Based on current browser locale the Dashboard can be displayed in one of the supported languages listed below. In case it does not work, make sure that your browser's locale is identified with correct language code.
| Language | Code |
--------------------|------|
| English (default) | en |
| French | fr |
| Japanese | ja |
## Building localized dashboard
To show localized dashboard, you need to build dashboard binary before.
To build dashboard binary, run `npm run build`. Or to run localized dashboard immediately, run `npm run start:prod`.
Note: Building localized dashboard takes time, so development environment, e.g. `npm start`, does not compile localized versions.
## Translation management
All translation data is stored in `i18n/` directory in project's root. It includes `locale_conf.json` configuration file, translation source file `messages.xlf` and localized files for each language, e.g. `messages.fr.xlf` or `messages.ja.xlf`.
## Introducing new localizable text
Localization is handled by [Angular](https://angular.io/guide/i18n).
Add `i18n` attribute into tag surrounding new text in Angular template html files.
### To update translation source file and localized files
Run `npm run fix:i18n`. It will execute `ng xi18n` and `xliffmerge`, they will update `i18n/messages.*` files.
### To translate new localizable text
`xliffmerge` would copy new localizable texts from `<source>` element to `<target>` element with `state="new"` attribute in your language file, i.e. `i18n/messages.[locale].xlf`.
Find new localizable texts in `i18n/messages.[locale].xlf` file and translate text in the `<target>` element.
## Introducing new language
1. Add your language code, e.g. `fr` or `ja`, into `"languages"` array of `"xfillmergeOptions"` in `package.json` file.
2. Run `npm run fix:i18n`. Then translation file for your language, e.g. `i18n/messages.fr.xlf` would be generated.
3. Open your language file and translate texts in `<target>` element into your language.
After preparation of new translation file, configure `i18n/locale conf.json` file to build newly localized dashboard as follows:
```
{"translations": [ "en", "fr" ]}
```
To add Japanese translation file, add `"ja"` into `"translations"` array.
```
{"translations": [ "en", "fr", "ja" ]}
```
Then you can build your localized dashboard with `npm run build`.
At last, please create Pull Request and submit it to `kubernetes/dashboard`.
Kubernetes Dashboard is a web-based user interface for Kubernetes clusters. It consists of multiple views like overview pages, list of resources and resource details pages. Much textual information is required within these elements. Let's consider sample dialog:
As you noticed there are a lot of different kinds of text messages in each view:
* Titles,
* Headers,
* Labels,
* Values,
* Tooltips,
* Action button,
* Menu and navigation entries,
* All kinds of messages including warnings, errors and help information.
For each one of them a developer has to make the following decisions:
* Grammar - Using a verb in infinitive or gerund form?
* Punctuation - Using a period or not?
* Capitalization - Using capitalized words? Capitalize Kubernetes specific names?
In addition, with few exceptions, all text messages within the Dashboard should be localized. For more details check our [internationalization guidelines](internationalization.md)).
## General terms
### Grammar
The gerund form should be used everywhere. Exceptions are all kinds of messages including warnings, errors and help information.
### Punctuation
Certain types of text resources should have punctuation. Periods should be used for
* All kinds of messages including warnings, errors and help information.
Periods should be avoided for:
* Headers,
* Titles,
* Labels,
* Values,
* Tooltips,
* Menu and navigation entries.
### Capitalization
In general, all kinds of messages should have their first word capitalized. Exceptions are:
* Names which appear in the middle of a message,
* Values and table contents.
Moreover, Kubernetes-specific names should be capitalized everywhere. This includes:
* Application names - Kubernetes, Kubernetes Dashboard etc.
* Resource names - Pod, Service, Endpoint, Node etc.
