Civic

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.

✨Demo Day⁇✨ You may notice a lot of references to Demo Day! Our most recent Demo Day was September 11, 2019 in Portland, OR. See highlights!

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:

   • nvm
   • yarn > 1.0

   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. You may need to install the appropriate version per npm instructions
$ nvm use

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

# This can take a minute, so take a stretch break (mental or physical)!

Text editor additions

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…)

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

Working on a single package other than the component library

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 2019-template package) and work on it as if it was a standalone project:

$ cd packages/{package-name} # e.g. cd package/2019-template

# run local project
$ yarn start

# 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

Creating a new component

It's as easy as running yarn component from the root of the repo. You'll be prompted to name your component. When that's done, it will add new files as seen here:

civic
└───packages
    └───component-library
        └───src
        │   └───YourNewComponent
        │           YourNewComponent.js
        │           YourNewComponent.test.js
        └───stories
                YourNewComponent.story.js
                yourNewComponent.notes.md

It will export YourNewComponent.js from component-library/src/index.js. It was also set up the YourNewComponent.story.js for you in storybook component-library/stories/index.js. You can now run yarn storybook from the root and see YourNewComponent under BasicInputs/YourNewComponent. You can also run yarn test within component-library/ and see that the YourNewComponent tests all pass. As you develop, make sure to update YourNewComponent.story.js, yourNewComponent.notes.md, and YourNewComponent.test.js so that future developers can easily understand how to use your work and rest easy that it is well tested!

Creating a new card

There are two options to create a card: from API data and from local json data. Our new card generator makes it easy to load data from the API so we recommend that approach for ease of creation and the most up to date data.

Using API data (recommended)

At the top of the repo run:

$ yarn card

This will bring up the prompt:

$ Which existing package should this card be in?: >

Type the name of a package that already exists in the civic/packages/ directory (example 2019-transportation) and press enter.

You will now see this prompt:

$ What will be the title of the card? (Capitalized With Spaces): >

Type the title of what you want to show on the new card and press enter. You may always change it later. Be aware that this choice will determine the names of newly created directories, files, and the import of those files into existing files.

You should see something like this now:

$ yarn card
yarn run v1.16.0
$ yarn hygen api-story-card with-prompt
$ /Users/Awesome_Volunteer/civic/node_modules/.bin/hygen api-story-card with-prompt
✔ Which existing package should this card be in?: · 2019-transportation
✔ What will be the title of the card? (Capitalized With Spaces): · Ducks Taking Buses

Loaded templates: _templates
      MANY INJECT AND ADDED MESSAGES
✨  Done in 37.18s.

If the package you chose isn't set up quite the way the generator expected you may need to make some modifications to files where code was injected but this should get you most of the way there. Now you can customize and hook in your own data.

Using local data (not recommended)

The process is very similar to genrating an API data based card. At the top of the repo run:

$ yarn card:local-data

You'll then follow the same prompts as above. When you've finished you'll see a similar output to the one above.

If the package you chose isn't set up quite the way the generator expected you may need to make some modifications to files where code was injected but this should get you most of the way there. Now you can customize and hook in your own data.

Creating a new Package

At the top of the repo run:

$ yarn new-package

This will bring up the prompt:

$ What do you want to name the new package? (e.g. YYYY-package-name): >

Type the name of the new package that you want to create and press enter. ✨ DONE ✨ You can now add a card if you want. Try it out using the Creating a new card

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. New packages in development for the 2019 project season.

• Year Packages
  • 2018 <- despite the name, this package powers civicplatform.org in 2019 and beyond.
  • 2017
• Project Packages
  • 2018-neighborhood-development
  • 2018-disaster-resilience
  • 2018-transportation-systems
  • 2018-housing-affordability
  • 2018-local-elections
  • 2018-example-farmers-markets
  • budget
  • emergency-response
  • homelessness
  • housing
  • transportation
• Utilities
  • civic-sandbox
  • civic-babel-presets
  • component-library
  • dev-server
  • mock-wrapper
  • webpack-common

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.