Skip to content
The frontend monorepo for the CIVIC platform.
Branch: master
Clone or download
Latest commit 4fa0daa Jul 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Create story-card-improve.md May 1, 2019
.storybook Created a CIVIC theme for Storybook. Branded CIVIC's Storybook with l… May 12, 2019
bin Third-party ecs-deploy script borrowed from how we handle API deploys May 22, 2018
packages merge master Jul 17, 2019
scripts Add start script to clarify no start in project root Apr 16, 2019
.editorconfig add some core config files Jul 30, 2017
.eslintrc Update .eslintrc Jun 10, 2019
.gitattributes Add .gitattributes file (#407) Jan 16, 2019
.gitignore add .vscode to .gitignore Jul 14, 2019
.nvmrc update node version Mar 12, 2019
.prettierignore add prettierignore Apr 10, 2019
.prettierrc prettier assorted Apr 10, 2019
.travis.yml set up publishing and automatic publishing Apr 22, 2019
.yarnrc fix issues with transportation & lin errs Nov 12, 2017
ARCHITECTURE.md RFC: Add Automatic Code Formatting Using Prettier (#417) Mar 2, 2019
CONTRIBUTING.md prettier assorted Apr 10, 2019
DATAVIZ.MD prettier assorted Apr 10, 2019
LICENSE add some core config files Jul 30, 2017
Makefile Boost the amount of memory available when deploying storybook May 23, 2019
README.md 39 yarn bootstrap includes build comp lib (#613) Jun 18, 2019
WORKING_WITH_REDUX.md prettier assorted Apr 10, 2019
babel.config.js prettier assorted Apr 10, 2019
compositor.json prettier assorted Apr 10, 2019
lerna.json revert publishing commits; Apr 27, 2019
package.json 39 yarn bootstrap includes build comp lib (#613) Jun 18, 2019
yarn.lock Merge branch 'master' into component-library/Checkbox Jul 14, 2019

README.md

Civic Build Status

This is the home of the front-end code for the CIVIC Platform. It's organized in a monorepo using Yarn Workspaces, but it's ok if you don't know what that means yet.

Let's make this better, together!

Civic magic happens when we work together. We welcome your collaborative contributions. We also have a more technical contribution guide.

🐧 I see something that could be better: The first step is open an issue, and tell us what you see that could be better. Tell us about your vision so that we can see what you see and help to improve it.

🐦 I want to work on making something specific better: If there's already a documented issue about what you want to work on, assign yourself to let others what you're working on. If there's not an issue, open one and assign yourself.

🐤 I want to work on making something better, but I'm not sure where to start: Check out our open issues with the good-first-issue label for things to work on and open pull requests with the good-first-review label to review and collaborate with others on existing efforts.

🦜 I've done something towards making this better: Fantastic! Share it with us by opening a pull request with what you've done so far, and let's work together to make it even better and incorporate it into the CIVIC Platform!

🦚 I want to explore more things:

CIVIC Platform 👏 Components and Style Guide (Storybook) 👏 Platform Architecture Guide 👏 Redux Guide 👏 Contributing Guide

Setup

Development environment

Prerequisites

Before you install and build, you'll need the following.

  1. bash

    You will need a Unix shell (bash). For Mac, this can be Terminal.app. For Windows, you'll need to use Windows Subsystem for Linux (see issue #53).

  2. nvm and yarn

    You will need the following tools installed in your Unix shell:

    These tools make sure every contributor has identical dependency versions, include node and node packages.

  3. git

    You will need to have Git installed in your bash environment.

Install and build

🐸GENTLE WARNING🐸: Make sure you have met the prerequisites ☝️

# Clone the repository using either https or ssh
# https
$ git clone https://github.com/hackoregon/civic.git
# OR ssh
$ git clone git@github.com:hackoregon/civic.git

$ cd civic

# Sets your Node.js version to match what the project uses.
$ nvm use

# Installs all package dependencies and links cross-dependencies.
# Also builds the component library
$ yarn bootstrap

# This can take a while (approximately 5mins), so grab some coffee☕️, tea🍵 or another beverage of your choosing.

# If you're getting an error like this one: "Your lockfile needs to be updated, but yarn was run with `--frozen-lockfile`",
# you may consider running
$ yarn install
# and then
$ yarn bootstrap

Setting up your text editor

In order to be the most productive, you’ll want to install some extensions or plug-ins for your text editor. These tools are already installed and configured project wide, so the only installation you’ll need is inside your text editor (don’t npm install or yarn add them). There are plug-ins or extensions available for the most commonly used editors (VS Code, Sublime Text, Vim, WebStorm, Atom, etc…)

🐸GENTLE WARNING🐸: Configuration still in progress. You may encounter linting errors. You may want to turn off Prettier and ESLint in your editor for the time being

  • EditorConfig — for consistency in settings like indentation line-endings
  • ESLint — to show linting in your editor as you’re coding
  • Prettier — for code formatting in your editor as you’re coding

Working on a single package other than the component library

At this point, Yarn has prepared all packages in the monorepo.

Most developers working in this project will be contributing to one package at a time.

This is the command sequence that will allow you to build/run an individual package every time (for example, the housing package) and work on it as if it was a standalone project:

$ cd packages/{package-name} # e.g. cd package/2018-disaster-resilience

# run local project
$ yarn start

# test local project
$ yarn test

# watch tests while working on them
$ yarn test --watch

Working on the component library using Storybook

We are committed to a shared component library. This is achieved using the component-library package and React Storybook. Run Storybook with the following command or view it here:

# run this command from project root (civic)
$ yarn storybook

Working on the component library and a project package simultaneuously

In separate terminals, run the commands in the Working on a single package other than the component library and Working on the component library using Storybook sections above. Project packages rely on the built version of the component library, so if you have updated the component library, and want to see your changes in the project package you are working on, you'll need to rebuild the component library. Once the component library build has finished, your project package will reload with the update components.

$ cd packages/component-library

# rebuild the component library
$ yarn build

Project Layout

There are three types of packages right now:

  1. Project packages: A React/Redux codebase that holds a collection of stories and API interactions for a single project in a Hack Oregon project cycle.
  2. Year package bundles: A React/Redux codebase that bundles together all project packages for a given year. This is a unit that gets deployed to production.
  3. Utilities: Common code that other projects depend on.

Packages

Every package has its own README with further details on what the package is for and how it works. We'll be adding some new packages for the 2019 project season.

Testing across all packages

To run all tests for all packages, use the following command:

yarn test

Tests for individual packages can be run from within the individual package's directory. Running all tests is useful for continuous integration environments as well as verifying changes to common dependencies does not break packages.

For example, run the above command at the root of the project after making changes to a component in the component library to ensure that others packages are compatible with the changes made.

Continuous Integration

Travis CI is configured to have a build pipeline for the component library and one for each project year. Although most commands are run using yarn scripts attached to a package.json file, due to the many steps required to run tests for a specific set of packages, a Makefile is used instead.

Continuous Delivery

Travis CI will deploy docker containers to ECS for each project year whenever the master branch builds successfully.

You can’t perform that action at this time.