feat(job-queue): deesigning methods

src/job-queue/README.md

@@ -0,0 +1,27 @@
+The goal of this job queue design is to process jobs in order, with each job
+moving through a pipeline of tasks that need to be completed.
+
+At any given time, a job is in one of a few given states, e.g. "queued". These
+states are explained below. Along with this, each job also has a "dispatched"
+flag. If this flag is set to true, it means this job is currently being
+processed. "Being processed" could mean anything; it depends entirely on the
+state a job's in. While a job is dispatched, it is no longer present in the
+priority queue of its respective state.
+
+## Job
+
+A job describes a scheduled build as it moves through the pipeline of states.
+The job queue datastructure keeps track of all jobs in a central red-black
+binary tree. For each state, a priority queue tracks in what order jobs should
+be processed.
+
+## States
+
+* `queued`: a job that's in the job queue but does not yet need to be executed
+  (as defined by its timestamp)
+* `ready`: a job that's scheduled for building, with all preprocessing tasks
+  fulfilled.
+* `build_finished`: a job whose build has finished, and is waiting for any
+  post-build tasks.
+* `failed`: a job whose processing failed at some point. Jobs in this state
+  include a failure report that describes in what state they failed, and why.