Skip to content

contributing

Jump to bottom Edit New page
Joe Wright edited this page Dec 4, 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, Java9 fails our clojure linting and is not supported at present when compiling.

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.

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

Schema

If you make changes to the store and want those changes to be persisted between loads you will need to update the JSON schema and re-generate the validation file by calling:

npm run build:schema-validator

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.

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