# Contributing to Kibana ## How issues work At any given time the Kibana team at Elastic is working on dozens of features and enhancements to Kibana and other projects at Elastic. When you file an issue we'll take the time to digest it, consider solutions, and weigh its applicability to both the broad Kibana user base and our own goals for the project. Once we've completed that process we will assign the issue a priority. - **P1**: A high priority issue that affects almost all Kibana users. Bugs that would cause incorrect results, security issues and features that would vastly improve the user experience for everyone. Work arounds for P1s generally don't exist without a code change. - **P2**: A broadly applicable, high visibility, issue that enhances the usability of Kibana for a majority users. - **P3**: Nice-to-have bug fixes or functionality. Work arounds for P3 items generally exist. - **P4**: Niche and special interest issues that may not fit our core goals. We would take a high quality pull for this if implemented in such a way that it does not meaningfully impact other functionality or existing code. Issues may also be labeled P4 if they would be better implemented in Elasticsearch. - **P5**: Highly niche or in opposition to our core goals. Should usually be closed. This doesn't mean we wouldn't take a pull for it, but if someone really wanted this they would be better off working on a plugin. The Kibana team will usually not work on P5 issues but may be willing to assist plugin developers on IRC. #### How to express the importance of an issue Let's just get this out there: **Feel free to +1 an issue**. That said, a +1 isn't a vote. We keep up on highly commented issues, but comments are but one of many reasons we might, or might not, work on an issue. A solid write up of your use case is more likely to make your case than a comment that says *+10000*. #### My issue isn't getting enough attention First of all, sorry about that, we want you to have a great time with Kibana! You should join us on IRC ([#kibana](https://kiwiirc.com/client/irc.freenode.net/?#kibana) on freenode) and chat about it. Github is terrible for conversations. With that out of the way, there are a number of variables that go into deciding what to work on. These include priority, impact, difficulty, applicability to use cases, and last, and importantly: What we feel like working on. ### I want to help! **Now we're talking**. If you have a bugfix or new feature that you would like to contribute to Kibana, please **find or open an issue about it before you start working on it.** Talk about what you would like to do. It may be that somebody is already working on it, or that there are particular issues that you should know about before implementing the change. We enjoy working with contributors to get their code accepted. There are many approaches to fixing a problem and it is important to find the best approach before writing too much code. ## How to contribute code ### Sign the contributor license agreement Please make sure you have signed the [Contributor License Agreement](http://www.elastic.co/contributor-agreement/). We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once. ### Development Environment Setup - Clone the kibana repo and move into it ```sh git clone https://github.com/elastic/kibana.git kibana cd kibana ``` - Install the version of node.js listed in the `.node-version` file (this is made easy with tools like [nvm](https://github.com/creationix/nvm) and [avn](https://github.com/wbyoung/avn)) ```sh nvm install "$(cat .node-version)" ``` - Install dependencies ```sh npm install ``` - Start elasticsearch Note: you need to have a java binary in `PATH` or set `JAVA_HOME`. ```sh npm run elasticsearch ``` - Start the development server. ```sh npm start ``` #### `config/kibana.dev.yml` The `config/kibana.yml` file stores user configuration directives. Since this file is checked into source control, however, developer preferences can't be saved without the risk of accidentally committing the modified version. To make customizing configuration easier during development, the Kibana CLI will look for a `config/kibana.dev.yml` file if run with the `--dev` flag. This file behaves just like the non-dev version and accepts any of the [standard settings](https://www.elastic.co/guide/en/kibana/master/kibana-server-properties.html). The `config/kibana.dev.yml` file is very commonly used to store some opt-in/**unsafe** optimizer tweaks which can significantly increase build performance. Below is a commonly used `config/kibana.dev.yml` file, but additional options can be found [in #4611](https://github.com/elastic/kibana/pull/4611#issue-99706918). ```yaml optimize: sourceMaps: '#cheap-source-map' # options -> http://webpack.github.io/docs/configuration.html#devtool unsafeCache: true lazyPrebuild: false ``` #### SSL When Kibana runs in development mode it will automatically use bundled SSL certificates. These certificates won't be trusted by your OS by default which will likely cause your browser to complain about the cert. You can deal with this in a few ways: 1. Supply your own cert using the `config/kibana.dev.yml` file. 1. Configure your OS to trust the cert: - OSX: https://www.accuweaver.com/2014/09/19/make-chrome-accept-a-self-signed-certificate-on-osx/ - Window: http://stackoverflow.com/a/1412118 - Linux: http://unix.stackexchange.com/a/90607 1. Click through the warning and accept future warnings. 1. Disable SSL with the `--no-ssl` flag: - `npm start -- --no-ssl` #### Linting A note about linting: We use [eslint](http://eslint.org) to check that the [styleguide](STYLEGUIDE.md) is being followed. It runs in a pre-commit hook and as a part of the tests, but most contributors integrate it with their code editors for real-time feedback. Here are some hints for getting eslint setup in your favorite editor: | Editor | Plugin | | --- | --- | --- | | Sublime | [SublimeLinter-eslint](https://github.com/roadhump/SublimeLinter-eslint#installation) | | Atom | [linter-eslint](https://github.com/AtomLinter/linter-eslint#installation) | | IntelliJ | Settings » Languages & Frameworks » JavaScript » Code Quality Tools » ESLint | | vi | [scrooloose/syntastic](https://github.com/scrooloose/syntastic) | Another tool we use for enforcing consistent coding style is Editorconfig, which can be set up by installing a plugin in your editor that dynamically updates its configuration. Take a look at the [Editorconfig](http://editorconfig.org/#download) site to find a plugin for your editor, and browse our [`.editorconfig`](https://github.com/elastic/kibana/blob/master/.editorconfig) file to see what config rules we set up. ### Testing and building To ensure that your changes will not break other functionality, please run the test suite and build process before submitting your pull request. Before running the tests you will need to install the projects dependencies as described above. Once that is complete just run: ```sh npm run test && npm run build ``` #### Testing and debugging tests The standard `npm run test` task runs several sub tasks and can take several minutes to complete, making debugging failures pretty painful. In order to ease the pain specialized tasks provide alternate methods for running the tests.
npm run test:quick
npm run test:server
or npm run test:browser
npm run test:dev
npm run mocha [test file or dir]
or npm run mocha:debug [test file or dir]
npm run test:dev -- --kbnServer.testsBundle.pluginId=some_special_plugin --kbnServer.plugin-path=../some_special_plugin
npm run test:ui
npm run test:ui:server
test:ui:runner
tasks. Once the server is started test:ui:runner
can be run multiple times without waiting for the server to start.npm run test:ui:runner
test:ui:server
task.