Merge pull request #391 from dssg/contribution

Contribution Guide [Resolves #387]

CONTRIBUTING.md

@@ -2,3 +2,33 @@
 
 If you make changes to the code that are appropriate to share with all counties, please open a pull request. The request will be reviewed by the development team at the Center for Data Science and Public Policy before being approved and merged.
 
+
+## Issues
+
+Whether it be an unexpected error, a design flaw, a typo in documentation, or a desired feature, we track all potential changes to the code in Github Issues. Our issues page is at https://github.com/dssg/matching-tool/issues - do a search first to see if the issue has been mentioned before. If so, feel free to add any new information or even just let the community know that you are experiencing the same problem.
+
+If your issue doesn't exist yet, [create it!](https://github.com/dssg/matching-tool/issues/new) Try and be as detailed as possible.
+
+If it's an unexpected error, the following types of information can be helpful:
+
+- what page you were on
+- the steps you took up until finding the error
+- a screenshot of the page at error time
+- any [browser console errors](https://kb.yoast.com/kb/how-to-find-javascript-errors-with-your-browsers-console/)
+- any [server-side errors](https://dssg.github.io/matching-tool/admin/troubleshooting/#general-troubleshooting-tools) that your systems administrator was able to find
+
+On the other hand, if it's an idea for a new feature or design change you'd like to make, the following information will help discussion:
+
+- What problem would this change solve?
+- Would this change help all users of the tool?
+
+
+## Development
+
+### Working with GitHub
+
+The general workflow for making a code change to submit to this repository is described at GitHub's [Forking Projects](https://guides.github.com/activities/forking/) tutorial.  If you are new to Git and GitHub in general, [GitHub's Guides](https://guides.github.com/) should be helpful in learning the basics.
+
+### Making changes to the code
+
+If you'd like to learn about making changes to the code, the [development section of the documentation site](https://dssg.github.io/matching-tool/dev/getting-started/) is the best place to start.

docs/mkdocs.yml

@@ -25,6 +25,7 @@ pages:
         - {Updating: admin/updating.md}
         - {Configuring the Matching Service: admin/matching.md}
     - For Developers:
+        - {Getting Started: dev/getting-started.md}
         - {Creating or Modifying a Schema: dev/schemas.md}
         - {Modifying the Webapp: dev/webapp.md}
         - {Modifying the Matching Service: dev/matching.md}

docs/sources/admin/install.md

@@ -9,9 +9,7 @@
 
 ## Deploy with Docker
 
-If you are deploying the matching tool with the goal of having users actively use it to upload real data, and you want that data to persist, follow the [Production](#production) section. If you just want to try out the tool with fake data and do active development on it, follow the [Development](#development) section.
-
-### Production
+If you are deploying the matching tool with the goal of having users actively use it to upload real data, and you want that data to persist, follow the [Production](#production) section. If you just want to try out the tool with fake data and do active development on it, follow the [Developer](/dev/getting-started) section.
 
 1. Set up a Postgres server. [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_GettingStarted.CreatingConnecting.PostgreSQL.html) is recommended, though you may set up and administrate your own if desired.
 2. Set up a machine/instance that will run the matching tool (see [requirements](#requirements) section for recommendations). Log into this machine; the rest of the steps assume that you are on the machine.
@@ -46,22 +44,7 @@ If you are deploying the matching tool with the goal of having users actively us
 	- Example: `./scripts/3_create_user mycounty [email protected] password hmis_service_stays jail_bookings`
 11. At this point, the web app should be running at port 80 on the machine.
 
-### Development
-
-1. Clone the git repository: `git clone https://github.com/dssg/matching-tool.git` (this will require git to be installed if the machine didn't come with it)
-2. `cd matching-tool` to change into the repository root directory.
-3. Install docker and docker-compose. If you are on an Ubuntu machine, you can use the included executable script `./scripts/1_install_docker` script as a convenience for doing so. Otherwise, refer to the [Docker](https://docs.docker.com/install) and [Docker Compose](https://docs.docker.com/compose/install/) documentation. If running the included install script, log out and back in when it completes as it will add your user to the 'docker' group, and that change requires a new login to take effect.
-4. Set up storage.
-    1. Option 1 (S3):
-	    - Open up your .env file and modify the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` variables with your values. Visit [Managing Access Keys for your AWS Account](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) if you don't have an access key yet.
-	    - Open up the webapp.env file and modify all the instances of `your-bucket` to an S3 bucket you want to use to store data.
-    2. Option 2 (Filesystem): [configuration changes](install.md#using-the-filesystem)
-5. Bring up the docker containers using our development docker-compose: `docker-compose -f docker-compose-dev.yml up`
-6. Initialize the database and users. You can use [this script](https://github.com/dssg/matching-tool/blob/master/scripts/development/create_test_users_docker.sh) to get set up easily, including a user `[email protected]` with password `password`, that you can use to log in: `sh scripts/development/create_test_users_docker.sh`
-7. At this point, the web app should be running at port 80 on the machine.
-
-
-### Using the Filesystem
+## Using the Filesystem
 
 The code in both the webapp and the matching service support both S3 and filesystem schemes for storage. However, since they need to communicate data between each other, and by default they are in separate Docker containers with separate filesystems, to use the filesystem you must also modify the docker-compose.yml to mount a shared volume from the host machine between the `webapp`, `webapp_worker`, and `matcher_worker` containers.
 

docs/sources/dev/getting-started.md

@@ -0,0 +1,17 @@
+# Getting Started 
+
+To make any changes to the matching tool, first you have to get the tool running on a computer.
+
+1. Clone the git repository: `git clone https://github.com/dssg/matching-tool.git` (this will require git to be installed if the machine didn't come with it)
+2. `cd matching-tool` to change into the repository root directory.
+3. Install docker and docker-compose. If you are on an Ubuntu machine, you can use the included executable script `./scripts/1_install_docker` script as a convenience for doing so. Otherwise, refer to the [Docker](https://docs.docker.com/install) and [Docker Compose](https://docs.docker.com/compose/install/) documentation. If running the included install script, log out and back in when it completes as it will add your user to the 'docker' group, and that change requires a new login to take effect.
+4. Set up storage.
+    1. Option 1 (S3):
+	    - Open up your .env file and modify the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` variables with your values. Visit [Managing Access Keys for your AWS Account](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) if you don't have an access key yet.
+	    - Open up the webapp.env file and modify all the instances of `your-bucket` to an S3 bucket you want to use to store data.
+    2. Option 2 (Filesystem): [configuration changes](/admin/install.md#using-the-filesystem)
+5. Bring up the docker containers using our development docker-compose: `docker-compose -f docker-compose-dev.yml up`
+6. Initialize the database and users. You can use [this script](https://github.com/dssg/matching-tool/blob/master/scripts/development/create_test_users_docker.sh) to get set up easily, including a user `[email protected]` with password `password`, that you can use to log in: `sh scripts/development/create_test_users_docker.sh`
+7. At this point, the web app should be running at port 80 on the machine.
+
+At this point, you can proceed to the following pages, which cover common types of changes that developers may want to make to the tool.

docs/sources/dev/webapp.md

@@ -4,11 +4,16 @@ The webapp can be modified for adding new APIs, plots or functionalities that wi
 
 ![diagram](diagram.png)
 
-## Database
-
 - [PostgreSQL](https://www.postgresql.org/): An open source object-relational database.
 - [alembic](http://alembic.zzzcomputing.com/en/latest/): A database migrations tool written by the author of [SQLAlchemy](https://www.sqlalchemy.org/).
 
+## Applying Changes
+
+Before we get into the deep dive, here's a reference on applying webapp changes to a running version of the matching tool.
+
+- If you make changes to Python code, the code itself will automatically make it to each needed container through the mounted volume designated in the docker-compose file. However, the containers have to apply the changes. The webapp container will do this automatically, as Flask is running in development mode. However, if you are changing asynchronous code that runs in the worker container (like validation code), you will have to restart the `webapp_worker` container. If you're not sure which type of code you are modifying, restart the container to be safe.
+- If you make changes to Javascript code, you have to recompile the JS file by running a command in the webapp container: `docker exec webapp -c 'cd frontend && npm run build'`. In addition, you may have to [force-refresh your browser](https://refreshyourcache.com/en/cache/) to ensure all of the new code is applied to your browser, at least until [this issue](https://github.com/dssg/matching-tool/issues/255) is fixed. 
+
 ## Backend
 
 The backend of the matching tool follows the general modern Flask patterns with some variations, and uses the Flask [Blueprints](http://flask.pocoo.org/docs/1.0/blueprints/) for better modularization of APIs. A blueprint can be seen as a collection of APIs and can be registered to the application. The template html files go to the `/templates` and all the static files go to the `/static`, including css files, icon, and the Javascript bundle.