Adopt a Drain SF Development and Deployment Processes

Development Workflow for Adopt-a-Drain SF

This document describes the development workflow in use for the Adopt-a-Drain implementation for the City of San Francisco.

Issue Tracking

• Use Github Issues for filing, collaborating on, and resolving issues
  • Use tags to make filtering easier
  • Make use of @<username> to tag users so that they are notified
  • See Mastering Issues for more guidance
• Use the Main Github Project for organizing and prioritizing issues.
  • After creating an issue, add it as a card to the board (unless it shouldn't be worked on in the near future).
    • Useful filter to use is:open is:issue -- this will show you only open issues.
  • Generally only issues should be added as cards to the board. If you are working on a pull request and an issue doesn't exist, create an issue for tracking purposes. This also makes it easier for other users to see what open issues there are.
  • Columns:
    • Backlog
      • Where issues should generally go first
    • Ready
      • Issues that are ready for development
      • Issues should sorted in priority order (highest at the top)
    • In-Progress
      • Issues that have an assignee that are actively in development
    • Blocked
      • Issues that are blocked by some other action (e.g. getting feedback)
    • Done
      • Completed issues
      • Will be cleaned on a regular basis

Development

See Installation for how to install and run the application on your local computer. Requires Ruby (rbenv is recommended) and PostgreSQL or Docker (to run postgresql via docker-compose).

Typical workflow:

• Find an issue that you wish to work on
• Assign yourself to the issue
• Move the issue to the In-Progress column on the project page
• Create a git branch locally
• Write code locally to resolve the issue
  • Make sure to include tests if appropriate
  • Use ./bin/rails s to run the application locally
  • Break up work into several commits if there are disparate changes
  • See a note about git commit messages to see notes about writing good commit messages
• Run the tests via ./bin/rake
• Push branch up to Github
• Open a pull request against the master branch
  • This will run tests via TravisCI
  • Tag individuals for feedback if appropriate
    • A Heroku review app will automatically be deployed with your changes
      • This review app can be used to solicit UI or UX feedback from others
      • The default users [email protected]/password and [email protected]/password will exist and can be used for testing (you can also register new users as usual)
  • For larger changes, ensure that you receive feedback before merging
• When the pull request is green and you've gotten feedback for larger changes, merge the pull request via the Github UI

Releasing changes

The application is hosted on Heroku as adoptadrainsf. There is also a staging application named adoptadrainsf-staging that you can access via Adopt-a-Drain SF Staging. Changes are generally pushed to staging first, and then promoted to production.

• See How Heroku Works for an overview of what Heroku is and how applications are deployed to it.
• All changes on the master branch will automatically be released to the adoptadrainsf-staging Heroku application
• You can promote these changes to the adoptadrainsf Heroku application (which is what serves Adopt-a-Drain SF via the Heroku Pipelines UI (or heroku pipelines:promote --app adoptadrainsf-staging if you have the Heroku Toolbelt installed).
  • Before doing this, use git diff with the refs currently deployed to staging and to production to determine the set of changes that are going to be released. Do some spot testing on the staging application to determine that the changes work as expected and that the critical user flows (drain adoption) haven't been broken.
  • Once released, verify that Adopt-a-Drain SF is still up