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.
- Node version 8 or greater.
- Project Eval Client
NOTE: steps 2-4 in this section should only be run the first time you use this repository.
Carefully follow the steps in CREDENTIALS.md.
node bin/authenticate.jsto finish setting up gmail credentials.
- You'll be prompted to visit a URL in your browser and to paste a code into the terminal.
Please do that.
Steps for use
1. Environment Variables
.env file for the following:
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
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
/edit. So, for example, in the URL
the spreadsheet ID is
- This will create a copy of
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.
- 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>
<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-outboxand save it to
7. Sending Emails
To send a test project email to yourself, in the terminal run:
node bin/send-mail.js <project-number>
<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_EMAILso that you can inspect them before actually sending.
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_EMAILso that it goes to all consultants.
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-outboxfolder in the
projectsdirectory (specified by arguments) and creates HTML emails and saves them to the corresponding
send-mail.js: Looks for HTML files in the specified directory and sends them either to developers or to us (as a test run).
csv directory holds CSVs of developer info, which are fetched from the
team-assignments repo by the
scripts/getCsv.sh script using git.
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.writeFilethat'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
html-outbox folder for each
of the four projects:
scripts directory holds shell/bash scripts.
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
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.
See the client docs for details on how
bin/server.js talks to the client
This is very much a work in progress. Here are some areas that need work:
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
undefinedbefore 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.
- Find a bug? Want a feature? Open an issue!
- All content is licensed under a CCBYNCSA 4.0 license.
- All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact firstname.lastname@example.org.