Add a user documentation for the CI
This documentation put in one place the information needed for
users that are not administrating the CI.
Change-Id: I502c26ba1ceaf0af706c34f62e448b97b5648ce8
diff --git a/README.md b/README.md
index 7f07b8a..706eee0 100644
--- a/README.md
+++ b/README.md
@@ -19,3 +19,5 @@
* [workflow](docs/workflow.md): explains the CI workflow, and
how you can test local changes with jenkins-staging
* [jobs](docs/jobs.md): explains what jobs are running on the CI
+* [user](docs/user.md): explains how to use the CI system for a Bazel
+ contributor.
diff --git a/docs/jobs.md b/docs/jobs.md
index 850d257..be5440d 100644
--- a/docs/jobs.md
+++ b/docs/jobs.md
@@ -1,16 +1,19 @@
# Jobs
-Two categories of job run on ci.bazel.io: bootstrap/maintenance and projects.
+Three categories of jobs run on ci.bazel.io: bootstrap/maintenance,
+projects, and hidden jobs.
## Bootstrap and maintenance
-3 jobs control the bootstrap and maintenance of Bazel:
+Four jobs control the bootstrap and maintenance of Bazel:
-* `Github-Trigger`: a control job, launched by a Github webhook, that triggers the `Global/pipeline` job
- if there is push to the master branch, to a release branch or to a release tag.
-* `Bazel-Bechmark` and `Bazel-Push-Benchmark-Output`: are job running
- continously to
-* `Global/pipeline` handles the global tests as well as the release process
+* `Github-Trigger`: A job that is automatically triggered (by a GitHub
+ webhook) every time someone or something pushes commits to the GitHub
+ master branch, to a GitHub release branch, or to a GitHub release
+ tag. This job then triggers the `Global/pipeline` job.
+* `Bazel-Benchmark` and `Bazel-Push-Benchmark-Output`: jobs running
+ continously to produce benchmarks of Bazel published at [perf.bazel.build](https://perf.bazel.build).
+* `Global/pipeline`: a job that handles the global tests as well as the release process
All those jobs have custom configuration files that can be found in `jenkins/jobs/*.xml.tpl`.
@@ -26,23 +29,10 @@
## Hidden jobs
-In addition to those jobs, some more "hidden jobs" exists on the ci:
-
-* `CR/gerrit-verifier` is a custom job to detect pending reviews on gerrit that
+* `CR/gerrit-verifier` is a job to detect pending reviews on Gerrit that
need validation (that have been marked as `Presubmit-Ready`).
-* `PR/_project_` is a copy of the job for _project_ that validates a Github Pull
- Request on _project_ with the latest release of Bazel. A pull request
- is validated when an pull request admin comments __test this please__
- or __retest this please__. It also auto-triggers this job when an
- admin pushes a pull request.
- - Admins for pull request are the people from either the
- [bazelbuild](https://github.com/bazelbuild) organization or the
- [google](https://github.com/google) organization.
- - Jenkins identifies those people as admins whose visibility is
- public. To make someone public, go to [the Bazel organization
- page](https://github.com/orgs/bazelbuild/people) (or the
- [Google organization page](https://github.com/orgs/google/people) respectively),
- look for the person's name, and change their visibility to public.
+* `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
diff --git a/docs/user.md b/docs/user.md
new file mode 100644
index 0000000..2c61a96
--- /dev/null
+++ b/docs/user.md
@@ -0,0 +1,69 @@
+# Using ci.bazel.io
+
+[Bazel CI](http://ci.bazel.io) tests Bazel and a variety of
+open-source project that use Bazel. The projects using Bazel are
+also used to validate Bazel changes.
+
+Bazel CI is testing both on presubmit (on a pending change) or on
+postsubmit (on the master branch). It also handles the release project
+of Bazel and the performance benchmarks.
+
+## Postsubmit
+
+Every project that runs on Bazel CI is run on postsubmit. It is done
+using the GitHub API and handled automatically if
+[bazel-io](https://github.com/bazel-io) has write access to the
+repository.
+
+## Presubmit
+
+The Bazel CI is able to run presubmit tests of changes from GitHub and
+from Gerrit.
+
+A GitHub pull request is tested when an pull request admin comments
+__test this please__ or __retest this please__. This presubmit job is
+also automatically triggered when an admin pushes a pull request.
+
+ - Admins for pull request are the people from either the
+ [bazelbuild](https://github.com/bazelbuild) organization or the
+ [google](https://github.com/google) organization.
+ - Jenkins identifies those people as admins whose visibility is
+ public. To make someone public, go to [the Bazel organization
+ page](https://github.com/orgs/bazelbuild/people) (or the
+ [Google organization page](https://github.com/orgs/google/people) respectively),
+ look for the person's name, and change their visibility to public.
+
+To vet pull request, [bazel-io](https://github.com/bazel-io) must have
+write access to the repository (automatic if in the bazelbuild
+organization).
+
+Tests on a Gerrit code review are triggered when someone marks the
+code review as `Presubmit-Ready+1`. It will update the review thread
+with the link to the test results and mark the code review as
+`Verified+1` or `Verified-1` depending on the result of the test. To
+retrigger a test, simply reset the `Presubmit-Ready` label.
+
+## Global tests
+
+In addition to pre- and postsubmit tests for an individual change, the
+Bazel CI performs a "global test" which builds Bazel from a branch, and
+uses that build of Bazel to run all the other jobs on the Bazel CI. It
+then produces a report comparing the global test results of this build
+of Bazel with the global test results from the latest release of
+Bazel.
+
+This report can be found at `http://ci.bazel.io/job/Global/job/pipeline/<buildNumber>/Downstream_projects/`,
+for instance for the last run it will be at
+[http://ci.bazel.io/job/Global/job/pipeline/lastBuild/Downstream_projects/](http://ci.bazel.io/job/Global/job/pipeline/lastBuild/Downstream_projects/).
+
+## Release process
+
+In addition to testing all the jobs, the global test handles pushing
+the artifacts that are created by a release branch to GCS and to the
+GitHub release system.
+
+## Performance benchmarks
+
+Performance benchmarks run once a day. This job triggers a run of the
+performance tests on each new commit. The performance for each commit
+is reported at [perf.bazel.build](https://perf.bazel.build).
