Follow the setup instructions for Gerrit backend developers where applicable.
Follow the instructions here to get and install Bazel.
Note: Switch between an old branch with bower_components and a new branch with ui-npm packages (or vice versa) can lead to some build errors. To avoid such errors clean up the build repository:
rm -rf node_modules/ \ polygerrit-ui/node_modules/ \ polygerrit-ui/app/node_modules \ tools/node_tools/node_modules bazel clean
If it doesn't help also try to run
bazel clean --expunge
The minimum nodejs version supported is 8.x+
# Debian experimental sudo apt-get install nodejs sudo apt-get install npm # OS X with Homebrew brew install node brew install npm
All other platforms: download from nodejs.org.
or use nvm - Node Version Manager.
Various steps below require installing additional npm packages. To start developing, it is enough to install only top-level packages with the following command:
# Install packages from root-level packages.json bazel fetch @npm//:node_modules
All other packages are installed by bazel when needed. If you want to install them manually, run the following commands:
# Install packages from polygerrit-ui/app/packages.json bazel fetch @ui_npm//:node_modules # Install packages from polygerrit-ui/packages.json bazel fetch @ui_dev_npm//:node_modules # Install packages from tools/node_tools/packages.json bazel fetch @ui_dev_npm//:node_modules
More information for installing and using nodejs rules can be found here https://bazelbuild.github.io/rules_nodejs/install.html
To test the local Polymer frontend against production data or a local test site execute:
./polygerrit-ui/run-server.sh // or npm run start
These commands start the simple hand-written Go webserver. Mostly it just switches between serving files locally and proxying the real server based on the file name. It also does some basic response rewriting, e.g. it patches the config/server/info response with plugin information provided on the command line:
./polygerrit-ui/run-server.sh --plugins=plugins/my_plugin/static/my_plugin.js,plugins/my_plugin/static/my_plugin.html
Start Go server and then visit http://localhost:8081
The biggest draw back of this method is that you cannot log in, so cannot test scenarios that require it.
To be able to bypass the auth and also help improve the productivity of Gerrit FE developers, we created this chrome extension: Gerrit FE Dev Helper.
It basically works as a proxy that will block / redirect requests from current sites to any given url base on certain rules.
The source code is in Gerrit - gerrit-fe-dev-helper, contributions are welcomed!
To use this extension, just follow its readme here.
Set up a local test site once:
For running a locally built Gerrit war against your test instance use this command.
If you want to serve the Polymer frontend directly from the sources in polygerrit_ui/app/ instead of from the war:
--dev-cdn option:$(bazel info output_base)/external/local_jdk/bin/java \ -DsourceRoot=$(bazel info workspace) \ -jar bazel-bin/gerrit.war daemon \ -d $GERRIT_SITE \ --console-log \ --dev-cdn http://localhost:8081
NOTE You can use any other cdn here, for example: https://cdn.googlesource.com/polygerrit_ui/678.0
For daily development you typically only want to run and debug individual tests. Run the local Go proxy server and navigate for example to http://localhost:8081/elements/shared/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:
npm test
To allow the tests to run in Safari:
To run Chrome tests in headless mode:
WCT_HEADLESS_MODE=1 WCT_ARGS='--verbose -l chrome' ./polygerrit-ui/app/run_test.sh
We follow the Google JavaScript Style Guide with a few exceptions. When in doubt, remain consistent with the code around you.
In addition, we encourage the use of ESLint. 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:
npm run eslint
node_modules/eslint/bin/eslint.js --ext .html,.js polygerrit-ui/app/$YOUR_DIR_HERE
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.
bazel test //polygerrit-ui/app:polylint_test
or
npm run polylint
Warning: This feature is temporary disabled, because it doesn't work with Polymer 2 and Polymer 3. Some of the checks are made by polymer linter.
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
These tests require the typescript and fried-twinkie npm packages.
To run on all files, execute the following command:
./polygerrit-ui/app/run_template_test.sh
or
npm run test-template
To run on a specific top level directory (ex: change-list)
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:
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_<TOP_LEVEL_DIRECTORY> --test_arg=<VIEW_NAME>
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_change-list --test_arg=gr-change-list-view
Our users report bugs / feature requests related to the UI through Monorail Issues - PolyGerrit.
If you want to help, feel free to grab one from those New issues without assignees and send us a change.
If you don't know who to assign to review your code change, you can use this special account: gerrit-fe-reviewers@api-project-164060093628.iam.gserviceaccount.com and just assign to that account, it will automatically pick two volunteers from the queue we have for FE reviewers.
If you are willing to join the queue and help the community review changes, you can create an issue through Monorail and request to join the queue! We will review your request and start from there.