Change jobroot_dir to job_dir in executor config

And document it.

Naming this parameter is surprisingly difficult, since, ultimately
it's the "root directory for the job directories".  We call the
job directories jobdirs.  So it's the jobdir root.  But other
directory names in zuul config files have a dir suffix.
jobdir_dir doesn't sound right.  jobroot_dir is what we went
with since it's the most correct thing that matches the existing
style (even though it's confusing for internal zuul devs because
it maps to a variable called jobdir_root).

Instead of that, just call it "job_dir", which again, isn't technically
the most accurate from a Zuul internals perspective, but conveys
what needs to be conveyed to someone installing zuul.

Change-Id: I1494258c12eda5d566bc7154a2e0746090d0eecd

doc/source/admin/components.rst

@@ -296,10 +296,29 @@ executor
      finger_port=79
 
 **git_dir**
-  Directory that Zuul should clone local git repositories to::
+  Directory that Zuul should clone local git repositories to.  The
+  executor keeps a local copy of every git repository it works with to
+  speed operations and perform speculative merging.
+
+  This should be on the same filesystem as **job_dir** so that when
+  git repos are cloned into the job workspaces, they can be
+  hard-linked to the local git cache.  Example::
 
      git_dir=/var/lib/zuul/git
 
+**job_dir**
+  Directory that Zuul should use to hold temporary job directories.
+  When each job is run, a new entry will be created under this
+  directory to hold the configuration and scratch workspace for that
+  job.  It will be deleted at the end of the job (unless the
+  `--keep-jobdir` command line option is specified).
+
+  This should be on the same filesystem as **git_dir** so that when
+  git repos are cloned into the job workspaces, they can be
+  hard-linked to the local git cache.  Example::
+
+     job_dir=/var/lib/zuul/jobs
+
 **log_config**
   Path to log config file for the executor process::
 

zuul/cmd/executor.py

@@ -82,7 +82,7 @@ class Executor(zuul.cmd.ZuulApp):
 
             self.log.info("Starting log streamer")
             streamer = zuul.lib.log_streamer.LogStreamer(
-                self.user, '0.0.0.0', self.finger_port, self.jobroot_dir)
+                self.user, '0.0.0.0', self.finger_port, self.job_dir)
 
             # Keep running until the parent dies:
             pipe_read = os.fdopen(pipe_read)
@@ -111,15 +111,15 @@ class Executor(zuul.cmd.ZuulApp):
 
         self.user = get_default(self.config, 'executor', 'user', 'zuul')
 
-        if self.config.has_option('executor', 'jobroot_dir'):
+        if self.config.has_option('executor', 'job_dir'):
-            self.jobroot_dir = os.path.expanduser(
+            self.job_dir = os.path.expanduser(
-                self.config.get('executor', 'jobroot_dir'))
+                self.config.get('executor', 'job_dir'))
-            if not os.path.isdir(self.jobroot_dir):
+            if not os.path.isdir(self.job_dir):
-                print("Invalid jobroot_dir: {jobroot_dir}".format(
+                print("Invalid job_dir: {job_dir}".format(
-                    jobroot_dir=self.jobroot_dir))
+                    job_dir=self.job_dir))
                 sys.exit(1)
         else:
-            self.jobroot_dir = tempfile.gettempdir()
+            self.job_dir = tempfile.gettempdir()
 
         self.setup_logging('executor', 'log_config')
         self.log = logging.getLogger("zuul.Executor")
@@ -134,7 +134,7 @@ class Executor(zuul.cmd.ZuulApp):
 
         ExecutorServer = zuul.executor.server.ExecutorServer
         self.executor = ExecutorServer(self.config, self.connections,
-                                       jobdir_root=self.jobroot_dir,
+                                       jobdir_root=self.job_dir,
                                        keep_jobdir=self.args.keep_jobdir,
                                        log_streaming_port=self.finger_port)
         self.executor.start()