No description, website, or topics provided.
Clone or download
Latest commit 926a839 Apr 2, 2019

README.md

General Assembly Logo

WDI Project Evaluation Server

This is a tool for generating WDI project evaluation emails and sending them. It is currently in a working prototype stage.

Gmail API Setup

To send emails with this script, you'll need to get Gmail API credentials.

Prerequisites

Initial Setup

  1. Run npm install.

NOTE: steps 2-4 in this section should only be run the first time you use this repository.

  1. Carefully follow the steps in CREDENTIALS.md.

  2. Run node bin/authenticate.js to finish setting up gmail credentials.

    • You'll be prompted to visit a URL in your browser and to paste a code into the terminal.
  3. Please do that.

Steps for use

1. Environment Variables

Create a .env file for the following:

  LEAD_EMAIL="<your-email>"
  FORWARD_EMAIL="<wdi-faculty-serve>"

2. Cohort Branch

Each cohort has their own branch on this repository. This is where we keep the results of evaluating their projects for future reference. Before checking out a cohort branch, ensure that master is up to date. Run:

git checkout master
git pull
git checkout <cohort number>/master
git rebase master

You'll now be on the proper cohort branch, and it will be up to date with master. If this is game-project, you'll need to add -b to that check out, and you can skip the rebase.

3. Check spreadsheet

The functionality of this script depends on a properly filled out spreadsheet. In particuliar, we're looking for a sheet title "Project [X] Info", where X is 1, 2, 3, or 4. This spreadsheet should be sent out to developers to fill out on the morning of their presentations.

You must ensure that this spreadsheet is accurately filled out before running this script!

4. Build JSON

To build the json for each developer/team, in the terminal run:

  node bin/setup-templates.js <cohort-number> <project-number> <spreadsheet-ID>
  • Project number is 1, 2, 3, or 4.
  • The spreadsheet ID comes from the URL of the "Project [x] Info" spreadsheet. Specifically, it is the part between the /d/ and the /edit. So, for example, in the URL
    https://docs.google.com/spreadsheets/d/13NQIDYNzdnJamSnsJPbdY0x3eYlGQff0gpHbDhp5LVw/edit#gid=0
    
    the spreadsheet ID is 13NQIDYNzdnJamSnsJPbdY0x3eYlGQff0gpHbDhp5LVw.
  • This will create a copy of templates/<?-project>.json to json-outbox/<developer-name>.json or json-outbox/<team-?>.jsonfor each developer/team.
  • After creating these templates, commit them. This makes it easier to see what we've changed later on.

5. Evaluate Projects

  • Set up the project-eval-client WebSocket Server
  • Run the WebSocket Server with node bin/server.js <project-number>
  • Run the following command, and share the result with the rest of the eval team. This is your IP address on the local network.
    sh scripts/getIpAddress.sh
  • You and the rest of the eval team should now follow the steps outlined in the project-eval-client README.
  • When you are done evaluating, kill the server with ctrl + c.
  • Add and commit all changes to JSON files.

6. Build HTML

To build the html email for each developer/team, in the terminal run:

  node bin/build-mail.js <project-number>
  • Where <project-number> is 1, 2, 3, or 4.
  • You will be prompted to enter the resubmittal date and lead name.
  • Fill each out carefully and press enter when ready.
  • This will build an HTML email for each JSON file projects/<project>/json-outbox and save it to projects/<project>/html-outbox.

7. Sending Emails

Test

To send a test project email to yourself, in the terminal run:

  node bin/send-mail.js <project-number>
  • Where <project-number> is 1, 2, 3, or 4.
  • This will not actually send the emails to developers or to the forwarding address.
  • It will send a copy of each email to LEAD_EMAIL so that you can inspect them before actually sending.

Actual

To send the actual project email to each developer/team, in the terminal run:

  node bin/send-mail.js <project-number> actual
  • This will send each email to the developer/team it belongs to and to the forwarding address in FORWARD_EMAIL so that it goes to all consultants.

Development

Design

Because of how this project evolved, it's basically structured as a collection of scripts that can be used in conjunction but are only weakly integrated. The files in the bin directory do most of the actual "business logic".

  • authenticate.js: Used to connect to the Gmail API. Likely only needs to run once per user. Not needed at all for the WebSocket server.
  • setup-templates.js: This scripts builds out a cohort full of JSON files based on the arguments that are passed in when you run it.
  • server.js: Run this file to spin up the WebSocket server and listen for connections. This file contains all the logic that pertains to the server.
  • build-mail.js: This script takes the contents a json-outbox folder in the projects directory (specified by arguments) and creates HTML emails and saves them to the corresponding html-outbox directory.
  • send-mail.js: Looks for HTML files in the specified directory and sends them either to developers or to us (as a test run).

The csv directory holds CSVs of developer info, which are fetched from the team-assignments repo by the scripts/getCsv.sh script using git.

The lib directory holds functions used by bin scripts that are long or complex enough to warrant their own file.

  • auth-and-call.js: This is Google's code, with the added functionality to execute a callback after succesfully connecting to the Gmail API.
  • write-file-safe.js: This is a wrapper around the native fs.writeFile that's safe to use with multiple connections triggering writes in rapid succession. It works by first writing to a temporary file, then replacing the old file with the contents of the new one. Cribbed from Stack Overflow.

The projects directory holds json-outbox and html-outbox folder for each of the four projects: game, team, full-stack, and capstone.

The scripts directory holds shell/bash scripts.

The templates directory holds JSON files that are used as templates to create one JSON file per developer to be edited by the WebSocket server and then turned into emails by bin/build-mail.js.

Note on branching: The intended workflow is that each cohort will have their own branch on this repo. All JSON files and emails created/changed during the evaluation process should be comitted and pushed.

WebSocket communication

See the client docs for details on how bin/server.js talks to the client over Websockets.

Future Improvements

This is very much a work in progress. Here are some areas that need work:

Add tests

This repo desperately needs robust tests so that we can feel confident that it will send correct emails and not fail randomly during evaluation. The first step is probably to add unit tests. This will be signifcantly easier, because it won't require simulating a client connection over WebSockets. We should add good unit tests for all major functionality that try a lot of different edge cases and invalid inputs to highlight areas where we need to handle errors better. It will also help prevent future regressions.

A secondary goal is to end-to-end tests. This will require simulating multiple client connections, and probably also actually sending emails somewhere and ensuring correctness. This will definitely take some research -- a great way to contribute would be to research WebSocket and email testing libraries.

Improve error handling and checking.

  • We really don't want to send borked emails to stressed out developers. One way to ensure that we don't would be to add functionality that searches the emails for things like null and undefined before sending them.
  • We also need better error/success feedback when emails are sent. This would probably require some digging into the Gmail API.

BCC emails to all instructors.

  • It's implimented in a somewhat hacky way now, but it works! We could try to do it through some official Google API functionality in future.

Other stuff.

License

  1. All content is licensed under a CC­BY­NC­SA 4.0 license.
  2. All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact legal@ga.co.