Skip to content

contributing

Jump to bottom Edit New page
Christopher Martin edited this page Oct 17, 2018 · 66 revisions

Prerequisites

You'll need the follow tools installed to run locally:

Optional:

Java

You will need at least Java 6, however it's recommended to install Java 8 as this is what the CI pipeline and production uses.

Note, I had some issues when trying to use Java 9 which resulted in me given up and rolling back to Java 8. If you are able to get it working please update this guide with instructions.

Node

It's recommended to install Node Version Manager and use that to install the correct version of Node.

If you choose to install Node manually the correct version can be found in the .nvmrc file.

Note for Mac OSX users, installing nvm via Homebrew is not recommended by the nvm team, you should use their install script instead.

Chrome & Firefox

Chrome is required as the pre-push.sh script will attempt to run the functional tests in that browser by default.

They can optionally be run in Firefox.

Drivers

We use WebDriverManager to automatically download the latest drivers so you shouldn't need to install these manually.

Leiningen

The repo includes a lein.sh script that will automatically download the latest version of Leiningen if you don't already have it installed.

Mac OSX

These tools can be easily installed on OSX using Homebrew.

Windows

The core team has never tried building on a Windows machine. Please help out by updating this section if any special steps are required!

Starting the server

You can run the develop.sh script to automatically watch all the sources and recompile, see the script for more information.

./develop.sh

Note, sourcing the develop script (. ./develop.sh) seems to cause it to fail and hang. Currently not sure why, if anyone knows why and can supply a fix please submit a PR!

As we serve the static files from the Clojure backend, hot reloading is currently not supported, so you'll need to manually refresh to see any changes in the browser.

Once you are ready, run the pre-push.sh which mimics what the CI server will build.

Fonts

Google API fonts can be downloaded for local hosting from localfont.

Icon font

The icon font is from IcoMoon and only includes the current set of icons used. If you wish to include more icons you can upload the icomoon.json file into the IcoMoon App to recreate the Nevergreen project and get the correct set of icons.

To actually update the font in the repo you'll need to:

  1. Generate Font in the IcoMoon App and download the zip it creates.
  2. Overwrite the files in src/client/common/fonts/icons with the corresponding files in the fonts folder from the zip
  3. Overwrite the contents of icon_font.scss with the contents of 'style.css' from the zip
    1. Update the paths e.g. fonts/icomoon.eot should be updated to common/fonts/icons/icomoon.eot
    2. You'll need to fix linting issues such as quote usage
  4. Re-download the project from the IcoMoon projects page and update icomoon.json file

What to work on?

We maintain a list of issues/features on GitHub. The core team will assign any issues they are working on to themselves, so anything else is fair game. If you want to try tackling an issue, make sure to leave a comment so someone else doesn't also start working on it at the same time.

Conversely if you no longer have the time to work on an issue, please leave another comment so someone can pick up the issue. ❤️

We also have a label good first issues that we use to mark issues that would be good for someone new to the codebase to try picking up.

Some gotchas

Building/running the client errors

  • Try running ulimit -n and if this is low (e.g. 256) try updating it with ulimit -n 1024.

  • Ensure your node version matches the version listed in the .nvmrc file.

  • Try deleting your node_modules folder and re-running npm install.

  • (MacOSX) Make sure nvm was installed via their install script and not Homebrew.

  • Run develop.sh and pre-push.sh without sourcing.

Functional tests failing to start

  • Check if the selenium-support and selenium-java server test dependencies are up to date in the project.clj file.

Contributors

Copyright © 2014 - 2024 Build Canaries

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

Add a custom sidebar
Clone this wiki locally