gerrit/polygerrit-ui/README.md

# PolyGerrit

## Installing [Bazel](https://bazel.build/)

Follow the instructions
[here](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_installation)
to get and install Bazel.

## Installing [Node.js](https://nodejs.org/en/download/) and npm packages

The minimum nodejs version supported is 8.x+

```sh
# Debian experimental
sudo apt-get install nodejs-legacy
sudo apt-get install npm

# OS X with Homebrew
brew install node
brew install npm
```

All other platforms: [download from
nodejs.org](https://nodejs.org/en/download/).

Various steps below require installing additional npm packages. The full list of
dependencies can be installed with:

```sh
npm install
```

It may complain about a missing `typescript@2.3.4` peer dependency, which is
harmless.

If you're interested in the details, keep reading.

## Local UI, Production Data

This is a quick and easy way to test your local changes against real data.
Unfortunately, you can't sign in, so testing certain features will require
you to use the "test data" technique described below.

### Running the server

To test the local UI against gerrit-review.googlesource.com:

```sh
./polygerrit-ui/run-server.sh
```

Then visit http://localhost:8081

## Local UI, Test Data

1. [Build Gerrit](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_gerrit_development_war_file)
2. Set up a local test site. Docs
   [here](https://gerrit-review.googlesource.com/Documentation/linux-quickstart.html) and
   [here](https://gerrit-review.googlesource.com/Documentation/dev-readme.html#init).

When your project is set up and works using the classic UI, run a test server
that serves PolyGerrit:

```sh
bazel build gerrit &&
  $(bazel info output_base)/external/local_jdk/bin/java -DsourceRoot=/path/to/my/checkout \
  -jar bazel-bin/gerrit.war daemon --polygerrit-dev \
  -d ../gerrit_testsite --console-log --show-stack-trace
```

Serving plugins

> Local dev plugins must be put inside of gerrit/plugins

Loading a single plugin file:

```sh
./polygerrit-ui/run-server.sh --plugins=plugins/my_plugin/static/my_plugin.js
```

Loading multiple plugin files:

```sh
./polygerrit-ui/run-server.sh --plugins=plugins/my_plugin/static/my_plugin.js,plugins/my_plugin/static/my_plugin.html
```

## Running Tests

This step requires the `web-component-tester` npm module.

Note: it may be necessary to add the options `--unsafe-perm=true --allow-root`
to the `npm install` command to avoid file permission errors.

For daily development you typically only want to run and debug individual tests.
Run the local [Go proxy server](#go-server) and navigate for example to
<http://localhost:8081/elements/change/gr-account-entry/gr-account-entry_test.html>.
Check "Disable cache" in the "Network" tab of Chrome's dev tools, so code
changes are picked up on "reload".

Our CI integration ensures that all tests are run when you upload a change to
Gerrit, but you can also run all tests locally in headless mode:

```sh
npm test
```

To allow the tests to run in Safari:

* In the Advanced preferences tab, check "Show Develop menu in menu bar".
* In the Develop menu, enable the "Allow Remote Automation" option.

To run Chrome tests in headless mode:

```sh
WCT_HEADLESS_MODE=1 WCT_ARGS='--verbose -l chrome' ./polygerrit-ui/app/run_test.sh
```

Toolchain requirements for headless mode:

* Chrome: 59+
* web-component-tester: v6.5.0+

## Style guide

We follow the [Google JavaScript Style Guide](https://google.github.io/styleguide/javascriptguide.xml)
with a few exceptions. When in doubt, remain consistent with the code around you.

In addition, we encourage the use of [ESLint](http://eslint.org/).
It is available as a command line utility, as well as a plugin for most editors
and IDEs.

`eslint-config-google` is a port of the Google JS Style Guide to an ESLint
config module, and `eslint-plugin-html` allows ESLint to lint scripts inside
HTML.
We have an .eslintrc.json config file in the polygerrit-ui/ directory configured
to enforce the preferred style of the PolyGerrit project.
After installing, you can use `eslint` on any new file you create.
In addition, you can supply the `--fix` flag to apply some suggested fixes for
simple style issues.
If you modify JS inside of `<script>` tags, like for test suites, you may have
to supply the `--ext .html` flag.

Some useful commands:

* To run ESLint on the whole app, less some dependency code:

```sh
npm run eslint
```

* To run ESLint on just the subdirectory you modified:

```sh
node_modules/eslint/bin/eslint.js --ext .html,.js polygerrit-ui/app/$YOUR_DIR_HERE
```

* To run the linter on all of your local changes:

```sh
git diff --name-only master | xargs node_modules/eslint/bin/eslint.js --ext .html,.js
```

We also use the `polylint` tool to lint use of Polymer. To install polylint,
execute the following command.

To run polylint, execute the following command.

```sh
bazel test //polygerrit-ui/app:polylint_test
```

or

```sh
npm run polylint
```

## Template Type Safety
Polymer elements are not type checked against the element definition, making it trivial to break the display when refactoring or moving code. We now run additional tests to help ensure that template types are checked.

A few notes to ensure that these tests pass
- Any functions with optional parameters will need closure annotations.
- Any Polymer parameters that are nullable or can be multiple types (other than the one explicitly delared) will need type annotations.

These tests require the `typescript` and `fried-twinkie` npm packages.

To run on all files, execute the following command:

```sh
./polygerrit-ui/app/run_template_test.sh
```

or

```sh
npm run test-template
```

To run on a specific top level directory (ex: change-list)
```sh
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_change-list
```

To run on a specific file (ex: gr-change-list-view), execute the following command:
```sh
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_<TOP_LEVEL_DIRECTORY> --test_arg=<VIEW_NAME>
```

```sh
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_change-list --test_arg=gr-change-list-view
```