Skip to content

contributing

Jump to bottom Edit New page
Christopher Martin edited this page Apr 15, 2019 · 66 revisions

Prerequisites

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

The following tools are optional but recommended:

Java

You will need at least Java 8 as that is required by Clojure 1.10.

The jabba Java version manager is supported and can be used to install the correct version of Java.

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.

CircleCI CLI

This can be used to validate the CircleCI configuration file is valid before pushing. See https://circleci.com/docs/2.0/local-cli/ for full details on installing and usage.

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

Import / Export feature

GitLab

For testing importing/exporting to GitLab locally you can use Docker with:

sudo docker run --detach \
        --hostname gitlab.example.com \
        --publish 443:443 --publish 80:80 \
        --name gitlab \
        --restart always \
        gitlab/gitlab-ce:latest

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.

  • If you previously installed node not via nvm your path might not get update correctly even if you install node for Nevergreen using nvm. Check your ~/.bashrc or ~/.bash_profile files to see if they manually add a path to node.

  • 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