improved documentation

README.md

@@ -1,6 +1,6 @@
 # Overview
 
-This repository contains the configuration files for the merge guards for the LLVM project. It configures a cluster of build machines that are used to check all incoming commits to the LLVM project.
+This repository contains the configuration files for the pre-merge checks for the LLVM project. This github project contains the documentation and the server configuration cluster of build machines that are used to check all incoming commits to the LLVM project.
 
 # Pre-merge check vision for end of 2019
 Maria is a developer working on a new idea for the LLVM project. When she submits a new diff to Phabricator (or updates an existing diff), the pre-merge checks are triggered automatically in the cloud. The pre-merge checks run in one configuration (amd64, Debian Testing, clang8) and comprise these steps:
@@ -55,63 +55,9 @@ On the Jenkins side:
 
 There is no backup of the credentials. If you need to change it, generate a new one and update it in Jenkins and Phabricator.
 
-# Playbooks
-
-## deployment to a clean infrastructure
-
-General remarks:
-* GCP does not route any traffic to your services unless the service is "healthy". It might take a few minutes after startup before the services is classified as healthy. Until then you will only see some generic error message.
-
-These are the steps to set up the build server on a clean infrastructure:
-1. Configure the tools on your local machine:
-    ```bash
-    ./local_setup.sh
-    ```
-1. Delete the old cluster, if it still exists:
-    ```bash
-    cd kubernetes/cluster
-    ./cluster_delete.sh
-    ```
-1. Create the cluster:
-    ```bash
-    cd kubernetes/cluster
-    ./cluster_create.sh
-    ```
-1. Create the disk storage, if it does not yet exist:
-    ```bash
-    cd kubernetes/cluster
-    ./disk_create.sh
-    ```
-1. SSH into the VM instance mounting the volume, find the mount point and then set
-    ```bash
-    # go to the mount point of the volume
-    cd  /var/lib/kubelet/plugins/kubernetes.io/gce-pd/mounts/jenkins-home
-    # change the permissions
-    sudo chmod a+rwx
-    ```
-1. Push the docker images to gcr.io:
-    ```bash
-    cd containers
-    #for each subfolder:
-    ./build_deploy.sh <foldername>
-    ```
-1. Deploy the stack:
-    ```bash
-    cd kubernetes
-    ./deploy.sh
-    ```
-1. Configure it
-
-## creating basic authentication for reverse proxy
-
-1. create auth file, based on [ingress-nginx documentation](https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/auth/basic)
-    ```bash
-    cd kubernetes/reverse-proxy
-    htpasswd -c auth <username>
-    # enter password at prompt
-    # add more users as required
-    kubectl create secret generic proxy-auth --from-file=auth --namespace=jenkins
-    ```
+# Additional Information
+* [Playbooks](docs/playbook.yaml) for installing/upgrading
+* [User documentation](docs/user_doc.md)
 
 # License
 This project is licensed unter the "Apache 2.0 with LLVM Exception" license. See [LICENSE](LICENSE) for details.

docs/playbooks.md

@@ -0,0 +1,58 @@
+# Playbooks
+
+
+## deployment to a clean infrastructure
+
+General remarks:
+* GCP does not route any traffic to your services unless the service is "healthy". It might take a few minutes after startup before the services is classified as healthy. Until then you will only see some generic error message.
+
+These are the steps to set up the build server on a clean infrastructure:
+1. Configure the tools on your local machine:
+    ```bash
+    ./local_setup.sh
+    ```
+1. Delete the old cluster, if it still exists:
+    ```bash
+    cd kubernetes/cluster
+    ./cluster_delete.sh
+    ```
+1. Create the cluster:
+    ```bash
+    cd kubernetes/cluster
+    ./cluster_create.sh
+    ```
+1. Create the disk storage, if it does not yet exist:
+    ```bash
+    cd kubernetes/cluster
+    ./disk_create.sh
+    ```
+1. SSH into the VM instance mounting the volume, find the mount point and then set
+    ```bash
+    # go to the mount point of the volume
+    cd  /var/lib/kubelet/plugins/kubernetes.io/gce-pd/mounts/jenkins-home
+    # change the permissions
+    sudo chmod a+rwx
+    ```
+1. Push the docker images to gcr.io:
+    ```bash
+    cd containers
+    #for each subfolder:
+    ./build_deploy.sh <foldername>
+    ```
+1. Deploy the stack:
+    ```bash
+    cd kubernetes
+    ./deploy.sh
+    ```
+1. Configure it
+
+## creating basic authentication for reverse proxy
+
+1. create auth file, based on [ingress-nginx documentation](https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/auth/basic)
+    ```bash
+    cd kubernetes/reverse-proxy
+    htpasswd -c auth <username>
+    # enter password at prompt
+    # add more users as required
+    kubectl create secret generic proxy-auth --from-file=auth --namespace=jenkins
+    ```

docs/user_doc.md

@@ -0,0 +1,17 @@
+# Sign up for beta test
+
+To sign up for the pre-merge tests, please add your user id to the [Herald rule](https://reviews.llvm.org/H511) triggering the builds. If you can't modify the rule yourself, please send an email to [kuhnel@google.com](mailto:kuhnel@google.com?subject=pre-merge%20beta%20testing).
+
+
+# Integration in Phabricator
+
+Once you're signed up, Phabricator will automatically trigger a build for every new patch you upload or every existing patch you modify. Phabricator shows the build results at the top of the entry:
+![build status](images/diff_detail.png)
+
+If a unit test failed, this is shown below the build status. You can also expand the unit test to see the details:
+![unit test results](images/unit_tests.png)
+
+After every build the build server will comment on your latest patch, so that you can also see the results for previous changes. The comment also contains a link to the log files:
+![bot comment](images/bot_comment.png)
+
+You can also trigger a build manually by using the "Run Plan Manually" link on the [Harbormaster page](https://reviews.llvm.org/harbormaster/plan/3/) and entering a revision ID in the pop-up window.