Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
200 lines (149 loc) · 9.68 KB

CONTRIBUTING.md

File metadata and controls

200 lines (149 loc) · 9.68 KB

Contributing Guide

We use GitHub issues for feature development and bug tracking.

Anyone is welcome to make an issue or a pull request. We would love for first-time contributors to pick one of our good first issue issues :)

Most contributors are DU members who collaborate in an internal Slack channel (#du-app), but we also welcome non-member contributors! To support that, we have a public mailing list. Feel free to ask any question: https://groups.google.com/a/doubleunion.org/forum/#!forum/public-du-code

If you're a DU member who would like access to Stripe test API keys for development, contact board@doubleunion.org.

Development setup

Do the below OR if you prefer Docker, see the Docker Setup section

Steps to get set up to develop and run tests

  1. Install Ruby. We use the version specified in .ruby-version.
    • Optionally, if you frequently work with Ruby and want to easily switch between versions, you might want to use a ruby version manager: rvm, rbenv, or chruby
    • If you installed a Ruby version manager, when you cd into the project directory, let your version manager install the ruby version in .ruby-version
  2. Install the bundler package managers:
gem install bundler -v 2.4.22
  1. Fork the repo (click the Fork button above), and clone your fork to your local machine. Here's a GitHub tutorial
  2. Install or start postgres.
    • On Mac, with Homebrew: brew install postgres. You can use the brew services command to start/stop/restart the database service, for exaple: brew services restart postgresql.
    • On Ubuntu: sudo apt-get install libpq-dev. To restart the database: sudo service postgresql restart. To query database service status: sudo service postgresql status.
    • Rails relies on the postgres role existing, but this role is not always created in a Postgres installation. If you run into connection errors complaining that the postgres role is missing, you can create it with the command: createuser -s -r postgres
    • See this article if you get stuck on Ubuntu: https://www.digitalocean.com/community/tutorials/how-to-use-postgresql-with-your-ruby-on-rails-application-on-ubuntu-14-04
  3. Install all dependencies (including Rails):

allow less strict function pointier types so that things can compile

bundle config build.nio4r --with-cflags="-Wno-error=incompatible-function-pointer-types"

then

$ bundle install
  • If you get errors about not being able to install the pg gem, you are likely missing postgres development libraries. To install those:
    • On Mac, with Homebrew: brew install postgres
    • On Ubuntu: sudo apt-get install libpq-dev
  1. Copy the configuration example files into their final locations:
$ cp config/database.example.yml config/database.yml
$ cp config/application.example.yml config/application.yml
  • The configuration in database.yml sets a blank password to connect to the local database. If your local postgres user has a different password, make sure to change that in the development and test sections of database.yml It's important that host is set to localhost in database.yml
  1. Set up the database:
$ bundle exec rake db:test:prepare

If this step fails on Ubuntu, make sure that your postgres db is up and running and that you only have one postgres instance up: try sudo lsof -i:5432. You may need to use sudo to set your /etc/postgresql/11/main/pg_hba.conf file. IPv4 local connections should say localhost under ADDRESS and trust under METHOD.

If this step fails on a Mac with Apple Silicon (the M chips) with TypeError: unable to resolve type 'size_t' , update ffi:

bundle update ffi
  1. Now you should be able to run tests locally, and they should all pass:
$ bundle exec rake spec

Steps to run arooo server locally

  1. bundle exec rake populate:users to set up dummy data

if you get FATAL: database "doubleunion_development" does not exist, you need to create the database first:

  bundle exec rake db:create
  bundle exec rake db:migrate
  1. bundle exec rails server don't forget to use http://localhost:3000 and not https
  2. bundle exec rails console Optional - useful for looking at and changing your local data)

Docker setup (optional)

  1. Install docker and docker compose

  2. Duplicate db config cp config/database.docker.yml config/database.yml

  3. build docker-compose build

  4. build docker-compose run --rm app bash -c bundle

  5. setup DB docker-compose run --rm app bundle exec rake db:setup

Set up an application for local OAuth:

  1. Github
  2. Google
    • Create a new set of Google OAuth credentials for your local server:
      • Go to the Google developers console > APIs & Services > Credentials (https://console.developers.google.com/apis/credentials)
      • Click on: Create credentials > OAuth Client ID
      • (If you're prompted to "Configure the consent screen", do that first. You should be able to enter "local server testing" as the application name, and leave all the other stuff blank.)
      • On the Create OAuth client ID screen:
      • Hit "Create", and copy the client id and client secret
    • Copy the client ID and client secret from your OAuth credentials into your local config/application.yml file, as the values for GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
    • For more details, see Google's instructions at https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred

Note that the callback URL you enter in GitHub or Google must match the URL you use to access your local server on. If you enter a callback URL of localhost:3000 and then access your local server on 127.0.0.1:3000, you will get a redirect callback mismatch error.

Common errors and gotchas

  1. If you see the error FATAL: role “postgres” does not exist, if you are on OSX with brew run /usr/local/Cellar/postgresql/<version>/bin/createuser -s postgres
  2. Arooo depends on a fork of the state_machine gem, because the original gem is no longer maintained. Fork is at https://github.com/compwron/state_machine, original gem is https://rubygems.org/gems/state_machine_deuxito .

Linting

bundle exec standardrb --fix # auto-fix linting issues (optional) more linter info

Tests

Tests, also known as specs, are great! Adding tests is a great pull request all on its own. Please try to write tests when you add or change functionality.

Run rake db:test:prepare after you pull or make any changes to the app, so make sure that your test database has the correct database schema

Make sure bundle exec rake spec passes before pushing your changes.

User states

The User state machine can be found in app/models/user.rb It is the main moving piece of the application.

Valid states:

  • visitor: default state, no admin access, no application access
  • applicant: not yet a member, no admin access, can only view/edit/save/submit their application
  • member: access to member admin section, cannot vote
  • key_member: access to member admin section, cannot vote, has keys to the space
  • voting_member: access to member admin section, can vote, has keys to the space

Manually changing a user's state

First, open a Rails console in a terminal window, from the same directory as the app:

rails console

Now you can update any user:

> user = User.find_by_username('someusername')
> user.state # => "visitor"

> user.make_applicant!  # => true
> user.make_member!     # => true
> user.make_key_member! # => true
> user.make_voting_member! # => true
> user.make_applicant!  # => raises invalid state transition error

> user.update_attribute(:state, 'applicant') # bypasses normal checks & succeeds

If you need to make or unmake an admin, have a current admin click the un/make admin button on a member in the Member Admin View. Admins can accept/reject applications, update any member's status, see current member's dues, open and close applications, and manage new member setup.

Door codes

In our new 2022 physical space, we use user.door_code (manually programmed into the physical door lock, then assigned to users via the app)