docs: restructure jobs.md
Change-Id: I5637e97a734b13614e3f4e7568540034bfff7a7a
diff --git a/docs/jobs.md b/docs/jobs.md
index 2f6cecd..d4fa119 100644
--- a/docs/jobs.md
+++ b/docs/jobs.md
@@ -1,39 +1,56 @@
# Jobs
-Three categories of jobs run on ci.bazel.io: bootstrap/maintenance,
-projects, and hidden jobs.
+Three categories of jobs run on https://ci.bazel.io:
+
+* bootstrap/maintenance jobs (e.g. bazel-bootstrap)
+* projects (e.g. TensorFlow)
+* hidden jobs
## Bootstrap and maintenance
Several jobs control the bootstrap and maintenance of Bazel, they
are mostly under the `maintenance` and `bazel` folders:
-* `benchmark`: job running continously to produce benchmarks of
- Bazel published at [perf.bazel.build](https://perf.bazel.build).
-* `maintenance/install-bazel`: job that install Bazel release on all the slaves.
-* `maintenance/gerrit-verifier`: job to detect pending reviews on Gerrit that
- need validation (that have been marked as `Presubmit-Ready`).
-* `bazel/nightly`: job that handles the global tests, it runs every night.
-* `bazel/release`: copy of `bazel/nightly` that runs for the release, it also
- handle publishing the release artifacts.
-* `bazel/presubmit`: copy of `bazel/nightly` that is triggered
- when someone set `Presubmit-Ready+2` on Gerrit.
+* `benchmark`: benchmarks Bazel performance
+
+ This job runs continuously and publishes results at https://perf.bazel.build
+
+* `maintenance/install-bazel`: installs Bazel release on all workers
+* `maintenance/gerrit-verifier`: detects pending reviews on Gerrit that
+ need validation.
+
+ A review needs validation if somebody marks it as `Presubmit-Ready`.
+
+* `bazel/nightly`: handles the [Global tests](docs/bazel-monitoring.md#global-tests)
+
+ This job runs every night.
+
+* `bazel/release`: copy of `bazel/nightly` that runs for the release
+
+ This job also handles publishing the release artifacts.
+
+* `bazel/presubmit`: copy of `bazel/nightly` that is triggered when someone
+ sets `Presubmit-Ready+2` on Gerrit
## Projects
-All the other jobs are defined by the `bazel_github_job` template that simply run
-Bazel on a github repository. The templates are in `jenkins/*.tpl` and the
-definitions in `jenkins/jobs/BUILD` and `jenkins/jobs/jobs.bzl`.
+These jobs simply run Bazel on a GitHub repository.
-The `JOBS` definition in `jenkins/jobs/jobs.bzl` is the list of jobs actually running on
-ci.bazel.io. On the staging, to make the full build faster, we use the `STAGING_JOBS` definition,
-which is a strip down version of the `JOBS` definition.
+The job templates and definitions are under `//jenkins`.
+
+Particularly interesting is `//jenkins/jobs/jobs.bzl`: it contains the logic
+that computes which jobs to run on the prod CI and on the staging CI.
+
+On the staging CI we run fewer jobs than on the prod one, to make full builds
+faster.
## Hidden jobs
-* `PR/_project_` is a copy of the job for _project_ that validates a GitHub pull
- request on _project_ with the latest release of Bazel.
-* `CR/_project_` is the same as `PR-_project_` but for validating Gerrit
- review request.
-* `Global/_project_` is another copy of the job but for use by the
- global presubmit test.
+These jobs are copies of the jobs for the corresponding `<project>`. These jobs
+all use the latest Bazel release:
+
+* `PR/<project>`: validates a GitHub pull request on `<project>`
+
+* `CR/<project>`: validates a Gerrit review request on `<project>`
+
+* `Global/<project>`: runs a global presubmit test for changes on `<project>`
