ShelterTech Web App

Docker-based Development Environment (Recommended)

Requirements

Docker Community Edition (CE) >= 17.06 Docker Compose >= 1.18

Follow the Docker installation instructions for your OS.

Set up the project

This is not a full guide to Docker and Docker Compose, so please consult other guides to learn more about those tools.

The docker-compose.yml is configured to mount the git repo on your host filesystem into the Docker container so that any changes you make on your host machine will be synced into the container and vice versa.

Creating the config.yml file

All config should be added in a file called config.yml. A sample config.example.yml is provided, you need to copy it and edit any parts that ask you to enter in your own information.

$ cp config.example.yml config.yml

# Open it in your preferred text editor

Algolia

Algolia is used as our search engine and in order for it to operate properly for everyone, we each need our own index.

• in config.yml set your github username as the value for ALGOLIA_INDEX_PREFIX. This will point to the search index matching your local environment.

Building and running the application

# Install node dependencies
$ docker-compose run --rm web npm install

# Build static assets bundle
$ docker-compose run --rm web npm run build

# Run dev server
$ docker-compose up

You should be able to view the web app in your browser at http://localhost:8080.

By default, this assumes that you have also set up askdarcel-api project using the Docker setup instructions and that the API server is running. If you want to target a different instance of askdarcel-api, you can modify the API_URL environment variable in docker-compose.yml.

Fully tearing down environment

In case you ever need to fully tear down your local development environment, such as to do a fresh setup from a clean slate, you will need to run extra commands to remove state that is stored in Docker. Removing the git repository and re-cloning is insufficient because some of the state is stored in Docker.

In particular, for performance reasons, we save NPM modules in a node_modules/ directory that is mounted from a Docker volume rather than bind mounting the node_modules/ directory from the host operating system (e.g. macOS). To delete all the installed NPM modules, you will have to remove the Docker volume.

The following command will stop all running Docker containers, delete them, and remove their volumes:

$ docker-compose down --remove-orphans --volumes

Note: When you run that command, you may get an error message about removing networks:

ERROR: error while removing network: network askdarcel id
4c4713d7f42173843437de3b0051a9d7e7bc81eb18123993975c3cd5a9e0a38e has active
endpoints

If this happens, then you need to run docker-compose stop in the askdarcel-api application first before running the docker-compose down command above.

Non-Docker Development Environment

Installing Node.js and npm

We recommend using nvm (Node Version Manager) or Docker to ensure that the versions of Node.js and npm are the same across development, Travis CI, staging, and production environments.

After installing nvm, to install both Node.js and npm run from the top of the git repo:

$ nvm install  # Reads from .nvmrc

Installing npm dependencies

To install the dependencies, from the top directory run

npm install

To build the bundled script with webpack run

npm run build

And to run the dev server, run

npm run dev

Branches and Deployments

There are two protected branches - development and main. Main is the default branch which will be the latest, stable codebase. Development will be where updates get deployed to a staging instance where QA can be performed. Any PR's created against these branches run a series of checks - like building the app, running unit tests, and linting the files.

There are two live instances - a staging instance and a production instance. Merges onto the development branch deploys the development branch to the staging isntance. Merges onto the main branch deploys the main branch to the production instance. See the github workflows for the details. Environment variables used in the deployments are set in github environments - 'prod' supplies the production instance and 'dev' supplies the staging instance..

Testing

We use Jest as a test runner and React Testing Library for component testing. Developers should become familiar with these tools.

Tests files should be co-located next to the source file in the file system and use the name of their source file with the suffix *.test.tsx.

app
└── components
    ├── MyComponent.tsx
    └── MyComponent.test.tsx

To run tests:

npm run test # Run all tests and exit
npm run test:watch # Watch files for changes and rerun tests related to changed files
npm run test:watch:all # Watch files for changes and rerun all tests when something changes

Acceptance testing

We do not currently support high-level acceptance testing that simulates workflows that cannot be tested through React Testing Library.

Pull Requests

Pull requests are opened to the development branch. When opening a pull request please fill out the as much of the pull request template you can, which includes tagging the issue your PR is related to, a description of your PR, indicating the type of change, including details for the reviewer about how to test your PR, and a testing checklist. Additionally, officially link the notion ticket to the PR using GitHub's linking UI.

When your PR is ready for review, add the needs review(s) label to help surface it to the other devs. You can assign people as reviewers to surface the work further. If you put up a PR that is not yet ready for eyes, add the wip label.

Once the PR has been approved, you either (1) squash and merge the commits if your changes are just in one package, or (2) rebase and merge your commits if your commits are cleanly separated across multiple packages to allow the versions to propagate appropriately.

As a reviewer on a PR, try not to leave only comments, but a clear next step action. If the PR requires further discussion or changes, mark it with Requested Changes. If a PR looks good to you (or even if there are small changes requested that won't require an additional review), please mark it with Approved and comment on the last few changes needed. This helps other reviewers better understand the state of PRs at the list view and prevents an additional unnecessary review cycle.