Skip to content

contributing

Jump to bottom Edit New page
Christopher Martin edited this page May 9, 2024 · 66 revisions

Prerequisites

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

The following tools are optional:

JVM

The SDKMAN! is supported and can be used to install the correct JVM version.

If you choose to install the JVM manually the correct version can be found in the .sdkmanrc file.

Node

Node Version Manager is supported and can be used 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/local-cli/ for full details on installing and usage.

Leiningen

The repo includes a lein.sh script that will automatically download the correct version of Leiningen.

Developing locally

The following major technologies and libraries are used.

Running

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!

Verifying changes

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

Prettier

The repo uses Prettier to format all supported files. The pre-push script and CI only run prettier check, which will fail the build if any files aren't correctly formatted.

Formatting using prettier is not done automatically. It is recommended to set up your IDE to automatically run prettier for you. You can also run npm run prettier to manually format all files using prettier.

Linting

The client uses ESLint to check TypeScript and Stylelint to check Sass.

The server uses eastwood to check Clojure.

Any style based rules for the client have been removed from the linters as we use Prettier to format consistently.

Tests

The client uses Jest and the React Testing Library for writing tests.

The server uses clojure.test for writing tests.

Journey tests are written using Cypress.

Commits

Commit messages should use the Conventional Commits format.

Features

State vs Configuration

Data imported or loaded from local storage is considered UntrustedData, which is just an object with unknown entries.

The first thing we do with UntrustedData data is migrate it, which produces UntrustedData.

We define the Redux reducer state using zod which gives us runtime types allowing us to verify and filter this UntrustedData to Configuration.

The Configuration is then dispatched as an action, and each reducer uses that to set it's own State.

Migrations

Migrations were based on Flyway database migrations. They operate entirely on UntrustedData and they must mutate the data given rather than return new data.

Note: the decision to mutate was made as it just turned out trying to write pure migrations resulted in more complicated, harder to read code 🤷

Hot reloading

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.

Fonts

The Google API fonts were downloaded for local hosting from localfont.

Icons

Icons are selected and saved from IcoMoon. The downloaded SVG file should be optimised with SVGR Playground.

A base Icon.tsx component has been created, so you should just be able to take the optimised path and pass it as a child to Icon e.g.

import React, { ReactElement, SVGProps } from 'react'
import { Icon } from './Icon'

export function MyNewIcon(props: SVGProps<SVGSVGElement>): ReactElement {
  return (
    <Icon {...props}>
      <path fill="#444" d="some path data"/>
    </Icon>
  )
}

See existing icons for real examples.

Backup

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

CI

The main CI pipeline is on CircleCi. For commits to main the full pipeline will run, for commits to other branches only the first "build" stage will run.

We also run all the tests using GitHub actions for all branches.

Either of these pipelines can be used to check your branch is working as expected. However, you should note the CircleCi pipeline does not run the journey tests for branches.

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

  • 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