Small tweaks to documentation

ORIENTATION.md

@@ -1,4 +1,4 @@
-# Our history
+## Our history
 We saw mutual aid groups for communities we are connected to -- and those across the US/world -- creating/sharing publicly-accessible spreadsheets of people asking for support that included lots of personally-identifying information including ways in which they’re vulnerable, identities, contact info, etc.
 
 Also saw some of the more tech-savvy groups trying to use lots of tabs within spreadsheets to organize the firehose and complexity of data.
@@ -14,11 +14,11 @@ We started off using a [Miro board](https://miro.com/app/board/o9J_kuKI5h8=/) fo
 Our team community norm: timing is difficult for everyone given the current uncertainties of our world, so we should communicate clearly that any of us might, at any time, have to back out from things we were hoping to accomplish. As a community, we prefer open and early communication about such things, and we want to make sure nobody feels pressured because circumstances have changed in a way they did not anticipate.
 
 
-# Priorities
-## People
+## Priorities
+### People
 * The groups we’re working with are "people first," and believe strongly in not referring to users as "offerers" or "askers," but instead the idea of seeing the whole person and their membership in the community as priority.
 
-## Holistic approach
+### Holistic approach
 * Existing platforms (e.g. marketplaces and even mutual aid specific ones) seem to focus on the listings feature exclusively, whereas we want to offer integration with mutual aid group operations (administration, pod mapping, resource sharing, fewer logins, central point of access granted/denied, etc)
 
 ## Features
@@ -67,7 +67,7 @@ Our team community norm: timing is difficult for everyone given the current unce
     * Import/export of listings, volunteers
 * Bug reporting
 
-# Current status
+## Current status (a bit out of date)
 * Basic CRUD for Community resources
 * Basic CRUD for offer and ask (one of those so far)
 * Switch to Bulma CSS
@@ -82,7 +82,7 @@ Our team community norm: timing is difficult for everyone given the current unce
 * CI
 * Initial README, CONTRIBUTING, code-of-conduct, LICENSE
 
-# What’s next
+## What’s next (also a bit out of date)
 * Outreach, dev team building, partnership with other groups
     * Code for America, Code for DC, Ruby for Good, Title Track, AHA
         * Concern: we don’t want to build the team into a mythical man month problem

README.md

@@ -58,7 +58,7 @@ Please, get involved! All of our communities could benefit from more resiliency
 
 ## Glossary
 We wrote up a [Glossary of terms](http://mutual-aid-demo.herokuapp.com/admin/glossary)  that's available in the demo instance once you're logged in.
-You can also review it [in code](blob/main/app/views/admin/glossary.html.erb).
+You can also review it [in code](app/views/admin/glossary.html.erb).
 
 ## Deploying the app
 Visit our [DEPLOYMENT.md](DEPLOYMENT.md) guide for more information on deploying the app.

SETUP.md

@@ -65,9 +65,9 @@ The Rails and webpack processes can be launched with Heroku, if you choose to go
 
 We've used the [dotenv](https://github.com/bkeepers/dotenv) gem to reference .env files in the main project level of the repo. Check out their README!
 We've provided example data, but please change them for your team, and, per their repo, you can save specific env files per environment, 
-e.g. (`env.development.local`, `env.text.local`). All of these are already in the gitignore, but we've kept `.env` in there bc `circleci` needs it.
+e.g. (`.env.development.local`, `.env.text.local`). All of these are already in the gitignore, but we've kept `.env` in there bc `circleci` needs it.
 
-(Remember to add them manually in Heroku or wherever you deploy!)
+Remember to configure environment variables in Heroku or wherever you deploy! Only the development environment uses `.env`
 
 
 ## Running the App!
@@ -99,21 +99,27 @@ Note: You only need mailcatcher if you're interested doing a lot of work on emai
 ### Run the App Locally
 
 Then, to run the app locally,
-
 ```
-$ bundle install
-$ yarn install
+$ bundle && yarn
 $ bin/rake db:rebuild_and_seed_dev
 $ bin/rails s # or, rails s -p 9000 (or whatever port you want to use that's not the default 3000)
 ```
 
-In development, webpacker runs a separate server to support automatic hot-swapping.
-This is only necessary when working on pages containing vue code, but will also speed up initial page loads on other pages.
-Run this in a separate terminal.
+In a separate terminal:
 ```
 $ bin/webpacker-dev-server
 ```
 
+Note about deprecation warnings. Ruby 2.7 deprecated some commonly used syntax so our codebase currently spits out a _lot_ of warnings.
+It will take some time for all our gems to get caught up, so in the meantime you might consider turning off deprecation warnings.
+There are [several ways](https://www.andrewm.codes/posts/hiding-ruby-2-7-deprecation-warnings-in-rails-6-2mil/) to do this.
+An alternative to the methods listed in the artice is to create an alias `alias nodep='export RUBYOPT="-W:no-deprecated"'`, giving
+you the flexibility to toggle warnings in each terminal session as appropriate.
+
+### Run tests
+See [TESTING.md](TESTING.md).
+
+
 ## Development with Docker
 
 The application includes a pre-configured [docker-compose](https://docs.docker.com/compose/) environment. This environment includes two containers, which together deploy the application and a postgres database for it to connect to.
@@ -141,13 +147,13 @@ To get started using the application with docker,
 
 8. You should now be able to reload `localhost:3000` in your browser. If everything went well, the website should appear and be functional. You can sign in using the email and password you set in the previous step. This docker compose also setups an a `mailcatcher` server, which you can access at `localhost:1080`. All emails will be delivered to mailcatcher, which should allow you to setup user accounts.
 
-**NOTE** Do not use this method in production! This is for **testing & development only* the configuration used with in this docker-compose file is highly insecure and should never be exposed to the public internet.
+**NOTE** Do not use this method in production! This is for **testing & development only** the configuration used with in this docker-compose file is highly insecure and should never be exposed to the public internet.
 
 Note that if you are developing this application, running `docker-compose up` a second time after you have made changes may not update the version of the application deployed by `docker-compose`. To ensure that `docker-compose` builds a new image that includes you changes, run `docker-compose up --build` instead.
 
 Also, if you would like docker-compose to run in daemon mode (which means that it will exit once the images have been set up and the application starts running) you may use `docker-compose up -d`. This will not show you any logging output from the application, however, and you will not be able to exit the application directly. To view logs when docker-compose is running in daemon mode, use `docker-compose logs`. To stop the application and all its services, run `docker-compose down`.
 
-**NOTE** the application will save its state between successively invocations of `docker-compose up --build`. This means that if you make changes to the database - for example by adding content or users - then those changes will persist the next time you start the application with `docker-compose`. You can wipe all the state of the application and all the services (including the postgres database) attached to it by running `docker-compose down --volumes --remove-orphans`. In particular, you may need to do this if you are making breaking changes to the database structure, or if you have corrupted something somehow. However, do be careful, because this will delete **all** the state saved in the application and database - and there is no way to retrieve it. So make sure you back up anything you want to save before running the command.
+**NOTE** the application will save its state between successive invocations of `docker-compose up --build`. This means that if you make changes to the database - for example by adding content or users - then those changes will persist the next time you start the application with `docker-compose`. You can wipe all the state of the application and all the services (including the postgres database) attached to it by running `docker-compose down --volumes --remove-orphans`. In particular, you may need to do this if you are making breaking changes to the database structure, or if you have corrupted something somehow. However, do be careful, because this will delete **all** the state saved in the application and database - and there is no way to retrieve it. So make sure you back up anything you want to save before running the command.
 
 
 ([Return to README.md](README.md))

TESTING.md

@@ -6,6 +6,11 @@ To run front end tests and back end tests individually:
 * Vue.js front end tests: `yarn test` or `yarn test -w` (mocha and chai are included in the `package.json` )
 * Rails front end and back end tests: `bin/rspec` (rspec is included in the Gemfile)
 
+Note that we currently rely on seeding in some of our backend specs, so before running `rspec`, first seed the test database:
+```
+bin/rake db:seed RAILS_ENV=test
+```
+
 ## Request specs
 When writing rspec tests within the spec/request directory, you can use `Warden::Test:Helpers`
 which give you access to the `login_as(user, :scope => :user)` method, as well as the `logout` method.