Dahlia

Cross-browser testing done with

Purpose

DAHLIA is the affordable housing portal for the City and County of San Francisco. It was created by the Mayor's Office of Housing and Community Development (MOHCD). This application streamlines the process of searching and applying for affordable housing, making it easier to rent, buy and stay in our City.

Technical Architecture

This repository contains the source code for housing.sfgov.org, which is the user-facing web application of the DAHLIA platform. It is a Ruby on Rails application that serves up a single page AngularJS app. The web application connects to a Salesforce backend (you can find the source code for that here), which is where the listings are actually created and administered. The primary purpose of the PostgreSQL database on the web application is to serve as user authentication (using Devise + Devise Token Auth), with every user in the database getting a salesforce_contact_id which corresponds to their record in the Salesforce database.

See here for the original Lucidchart of the above diagram

Dependencies

Before you install DAHLIA, your system should have the following:

• Ruby 2.3.7 (Use RVM or rbenv)
• Bundler gem install bundler
• Homebrew
• PostgreSQL
• Node.js 6.11.1
  • can use installer from nodejs.org or see: installing NVM and node.js on MacOS

Getting started

1. Make sure your PostgreSQL server is running (e.g. using Postgres.app listed above)
2. Open a terminal window
3. git clone https://github.com/Exygy/sf-dahlia-web.git to create the project directory
4. cd sf-dahlia-web to open the directory
5. bundle install to download all necessary gems
   • see here if you have issues installing pg gem with Postgres.app, you may need to use: gem install pg -v 0.18.4 -- --with-pg-config=/Applications/Postgres.app/Contents/Versions/latest/bin/pg_config
6. npm install to install bower, grunt and other dependencies (which will also automatically bower install to load front-end JS libraries)
7. overcommit --install to install git hooks into the repo
8. rake db:create && rake db:migrate to create the dev database and migrate the DB tables
9. copy .env.sample into a file called .env, and copy correct Salesforce environment credentials (not shared publicly in this repo)
10. rails s to start the server, which will now be running at http://localhost:3000 by default

Running Tests

To run ruby tests:

• rake spec

To run javascript unit tests:

• rake jasmine:ci to run in terminal
• rake jasmine to then run tests interactively at http://localhost:8888/

To run E2E tests:

• Installation (needs to be run once): ./node_modules/protractor/bin/webdriver-manager update to get the selenium webdriver installed
• On one tab have your Rails server running: rails s
• On another tab, run npm run protractor to run the selenium webdriver and protractor tests. A Chrome browser will pop up and you will see it step through each of the tests.

Note: These tests will run on Semaphore (our CI) as well for every review app and QA deploy.

Importing pattern library styles

We currently manually transfer the application's CSS from our pattern library using Grunt.

To update this app with the latest PL styles:

1. Clone the PL repository in the same parent directory as this one.
2. Optional: switch to the PL branch you want to import styles from.
3. cd to your sf-dahlia-web folder
4. Run grunt

We use grunt-clean and grunt-copy to transfer the CSS, and grunt-replace to replace relative background image paths with Rails asset URLs.

Acceptance/Feature Apps

Temporary "acceptance" apps are created upon opening a pull request for a feature branch. After the pull request is closed, the acceptance app is automatically spun down. See this Heroku article for details.

Contributing changes

Use the engineering workflow and coding style standards established below. 😃

Engineering Workflow Overview

Dahlia's current engineering workflow has been fully documented and can be found here.

Dahlia's project backlog is in Pivotal Tracker.

Code style and quality

Javascript

Javascript code quality is ensured by two npm packages: JsHint and JSCS. They will run automatically as a pre-commit hooks. Follow the Airbnb JavaScript Style guide.

Ruby

Rubocop is configured in .rubocop.yml to enforce code quality and style standards based on the Ruby Style Guide and runs every time you commit using a pre-commit hook. Refer to the Ruby Style Guide for all Ruby style questions. To identify and have Rubocop automatically correct violations when possible, run:

• rubocop -a [path_to_file] for individual files
• rubocop -a for all Ruby files

Changing the Style Guide settings

Any changes to Rubocop, JSCS, etc. affect the entire team, so it should be a group decision before commiting any changes. Please don't commit changes without discussing with the team first.

Credits

License

Copyright (C) 2015 City and County of San Francisco

DAHLIA is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with DAHLIA. If not, see http://choosealicense.com/licenses/gpl-3.0/