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).