Skip to content
This repository has been archived by the owner on Mar 8, 2022. It is now read-only.

Contributor Guide

Jump to bottom
Mica Cardillo edited this page Apr 14, 2020 · 24 revisions

Introduction

The concept was developed by a group of five volunteers in Ashland, Oregon and was operational within the first week. Here is an article about the Adopt a Neighbor Ashland to get a feel for how concept works and the impact it has on real citizens during the Covid-19 pandemic.

Getting Started

A step-by-step guide on how to get your local development environment up and running is coming soon! In the meantime, join our development channel in the Rogue Hack Lab's Slack account. To begin onboarding, find the Slack account by visiting Rogue Hack Lab's website and looking for the Slack widget to invite yourself. Once you're into the Rogue Hack Lab's Slack, then be sure to join the #adopt-a-neighbor-dev channel.

Less-Technical Support Roles for Volunteers

  • Help generating representative fake data we can use for demo purposes (since we can't use real people's addresses).
  • Graphic design / branding.
  • Serve as a guinea pig by trying to setup fake Adopt a Neighbor community with the instructions provided. Start by trying to setup with the low tech solution currently available here: https://www.adoptneighbor.org/adopt-a-neighbor-replication.
  • Manual quality assurance and testing.
  • Clarifying and improving documentation.
  • Managing social media accounts for the overall project.
  • Legal assistance (help us by reviewing draft Privacy Policy, Terms and Conditions, and general disclaimers here on the project repository and the public-facing sites.
  • Starting, coordinating, and promoting a Go Fund Me campaign for helping pay for the hosting costs (once we're rolling with a viable platform).
  • Community Outreach (finding community organizers in other communities and letting them know that the program can be replicated).

Developer Roadmap

Visit the Developer Roadmap to learn more about what we need to build and how we need to phase that work.

Development Philosophy and Technology Stack

The technology stack can be summarized as JavaScript with modern development practices, functional programming concepts, and a preference for proven, maintainable platforms and libraries and the ability to scale the development team in a way that allows all team members to be productive. Here are some of the early key decisions made so far:

  • Automated deployments on check-in to the develop branch, the master branch, and pull requests.
  • Service-oriented architecture, with microservices only when the overhead makes sense (different engineers working on it, different language, etc).
  • Self encapsulation (aka small, well-encapsulated units) with unit tests.
  • Code quality through automatic linting and code formatting before commit.
  • Quality review before merging PR into develop branch.
  • Minimizing overhead for sharing code between services (aka "monorepo").
  • Full control over how the application renders (no Bootstrap and jQuery).
  • Security is of critical importance as it relates to protecting the participant's private data.
  • The mantra of "move fast and break stuff" does not apply here. Move as fast as we can and don't try to be perfect. However, take the time to write readable code with clean, focused functions that can be easily unit tested.
  • Readable code is verbose code. Don't write abbreviated names for variables and functions.
  • If a module is getting so big, turn it into a directory with an index.js and import the pieces into the index.js. Example: my-module-name/index.js, my-module-name/lol-cats.js, my-module-name/lol-cats.spec.js, etc.
  • Since frontend is getting compiled to browser-friendly code anyway, try to co-locate test files next to the files they're testing and let the compiler do the work. This minimizes cognitive overhead and makes it easier to refactor later.

Tech Stack Details

General Developer Tools and Environment

  • Node LTS (currently Node 12.X)
  • Yarn
  • Docker (for running service dependencies locally, such as PostgreSQL and Redis)
  • Git/Github following standard Gitflow (for pushing up code, PR to develop branch, and bug tracking)
  • Trello boards to help track status of features and tasks (we might switch to Github at some point for this).

Frontend Choices

  • React (React native later on for when we get to mobile app development).
  • Grommet v2 (for baseline primitive components).
  • Redux (state management).
  • Redux Sagas (to manage and test side effects in a robust way).
  • Selectors (for memorization of derived state).
  • Styled Components with themes (aka CSS in JavaScript; unique CSS classes generated and de-duplication at compile time).

API Choices

  • Hapi (somewhat opinionated to decrease choices, but still scalable and meets most common needs, large open source community, adequate security modules).
  • Joi (defacto validation library for Hapi).
  • Other microservices may be incorporated including non-JavaScript, including docker images.
  • We plan on rolling an open source CMS called Strapi into our solution.
  • We should not role our own email server for transactional emails. SendGrid has a free tier, 100 emails per day, and the full plan is free for the first 30 days.

Database(s)

  1. Postgresql is a common-purpose database option that provides both JSON and tabular storage options, and most experienced software engineers know how to work with it.
  • Redis for caching and message queues. Latest preview version should have SSL encryption.

DevOps/Automation

  • Render is our current platform for continuous automated deployment and will most likely meet most of our needs as we scale out the system.
  • We are leveraging Cloudflare for a number of capabilities that will help us scale, cache, and secure our deployed systems.
Clone this wiki locally