Improve Prow development docs a bit.

prow/build_test_update.md

@@ -20,7 +20,41 @@ bazel build //prow/cmd/hook
 bazel test //prow/plugins/lgtm:go_default_test
 ```
 
-**TODO**(cjwagner): Unify and document how to run prow components locally.
+### How to test a plugin
+
+If you are making changes to a Prow plugin you can test the new behavior by sending fake webhook events with [`phony`](/prow/cmd/phony#phony).
+
+## How to update the cluster
+
+Any modifications to Go code will require redeploying the affected binaries.
+Assuming your prow components have multiple replicas, this will result in no downtime.
+
+Update your deployment (optionally build/pushing the image) to a new image with:
+```shell
+# export PROW_REPO_OVERRIDE=gcr.io/k8s-prow  # optionally override project
+push.sh  # Build and push the current repo state.
+bump.sh --list  # Choose a recent published version
+bump.sh v20181002-deadbeef # Use a specific version
+```
+
+Once your deployment files are updated, please update these resources on your cluster:
+
+```shell
+# Set the kubectl context you want to use
+export PROW_CLUSTER_OVERRIDE=gke_my-project_my-zone_my-cluster # or whatever the correct value is
+export BUILD_CLUSTER_OVERRIDE=gke_my-project_my-zone_my-cluster # or whatever the correct value is
+
+# Generally just do
+bazel run //prow/cluster:production.apply # deploy everything
+
+# In case of an emergency hook update
+bazel run //prow/cluster:hook.apply # just update hook
+
+# This is equivalent to doing the following with kubectl directly:
+kubectl config use-context gke_my-project_my-zone_my-cluster
+kubectl apply -f prow/cluster/*.yaml
+kubectl apply -f prow/cluster/hook_deployment.yaml
+```
 
 ## How to test a ProwJob
 
@@ -64,35 +98,3 @@ number.
 
 NOTE: It is dangerous to create ProwJobs from handcrafted YAML. Please use `mkpj`
 to generate ProwJob YAML.
-
-## How to update the cluster
-
-Any modifications to Go code will require redeploying the affected binaries.
-Assuming your prow components have multiple replicas, this will result in no downtime.
-
-Update your deployment (optionally build/pushing the image) to a new image with:
-```shell
-# export PROW_REPO_OVERRIDE=gcr.io/k8s-prow  # optionally override project
-bump.sh --list  # Choose a recent published version
-bump.sh --push  # Build and push the current repo state (and use this version).
-bump.sh v20181002-deadbeef # Use a specific version
-```
-
-Once your deployment files are updated, please update these resources on your cluster:
-
-```shell
-# Set the kubectl context you want to use
-export PROW_CLUSTER_OVERRIDE=gke_my-project_my-zone_my-cluster # or whatever the correct value is
-export BUILD_CLUSTER_OVERRIDE=gke_my-project_my-zone_my-cluster # or whatever the correct value is
-
-# Generally just do
-bazel run //prow/cluster:production.apply # deploy everything
-
-# In case of an emergency hook update
-bazel run //prow/cluster:hook.apply # just update hook
-
-# This is equivalent to doing the following with kubectl directly:
-kubectl config use-context gke_my-project_my-zone_my-cluster
-kubectl apply -f prow/cluster/*.yaml
-kubectl apply -f prow/cluster/hook_deployment.yaml
-```

prow/cmd/phony/README.md

@@ -3,8 +3,7 @@
 `phony` sends fake GitHub webhooks.
 
 ## Running a GitHub event manager
-`phony` is most commonly used for testing [hook](../hook), but can be used for testing any
-externally exposed service configured to receive GitHub events.
+`phony` is most commonly used for testing [`hook`](../hook) and its [plugins](/prow/plugins), but can be used for testing any externally exposed service configured to receive GitHub events (external plugins).
 
 To get an idea of `phony`'s behavior, start a local instance of `hook` with
 this:
@@ -34,4 +33,4 @@ If you are testing `hook` and successfully sent the webhook from `phony`, you sh
 {"author":"","component":"hook","event-GUID":"GUID","event-type":"pull_request","level":"info","msg":"Pull request .","org":"","pr":0,"repo":"","time":"2018-05-29T11:38:57-07:00","url":""}
 ```
 
-A list of supported events can be found in the [GitHub API Docs](https://developer.github.com/v3/activity/events/types/).
+A list of supported events can be found in the [GitHub API Docs](https://developer.github.com/v3/activity/events/types/). Some example event payloads can be found in the [`examples`](/prow/cmd/phony/examples) directory.

prow/jobs.md

@@ -100,8 +100,8 @@ conditions are met.
 
 #### Triggering Jobs With Comments
 
-A developer may trigger jobs by posting a comment to a pull request that contains
-one or more of the following phrases:
+A developer may trigger presubmits by posting a comment to a pull request that
+contains one or more of the following phrases:
  - `/test job-name` : When posting `/test job-name`, any jobs with matching triggers
    will be triggered unconditionally.
  - `/retest` : When posting `/retest`, two types of jobs will be triggered:
@@ -118,9 +118,8 @@ to Prow in some other context, like `/close`. It is similarly not suggested to d
 
 #### Posting GitHub Status Contexts
 
-Jobs that run will always post a status context to the commit under test in GitHub.
-Jobs that run conditionally but do not match the content of the pull request will
-_not_ post "Skipped" status contexts to the pull request.
+Presubmits that do not have `skip_report: true` will always post a status context to the commit under test in GitHub.
+Jobs that run conditionally but do not match the content of the pull request will _not_ post "Skipped" status contexts to the pull request.
 <!--- TODO(skuznets|fejta): remove mention of negative behavior by July --->
 
 If a conditional job matched a pull request at some point in the past, ran and failed
@@ -139,8 +138,7 @@ Tide will treat jobs in the following manner for merging:
  - unconditionally run jobs with required status contexts are always required to have
    passed on a pull request to merge
  - conditionally run jobs with required status contexts are required to have passed on
-   a pull request to merge if they have been triggered against the pull request during
-   its lifetime
+   a pull request to merge if the job currently matches the pull request.
  - jobs with optional status contexts are ignored when merging
 
 In order to set a job's context to be optional, set `optional: true` on the job. If it

prow/more_prow.md

@@ -14,6 +14,8 @@ Some Prow components expose prometheus metrics that can be used for monitoring,
 
 * If you find that your GitHub bot is running low on API tokens consider using [`ghproxy`](/ghproxy) to cache requests to GitHub and take advantage of the strange re-validation rules that allow for additional API token savings.
 * [Testgrid](/testgrid) provides a highly configurable visual overview of test results and can be configured to send alerts for failing or stale results. Testgrid is in the process of being open sourced, but until it has completely made the switch OSS users will need to use the https://testgrid.k8s.io instance that is managed by the GKE-Engprod team.
+* [Kind](https://github.com/kubernetes-sigs/kind) lets you run an entire Kubernetes cluster in a container. This makes it fast and easy for ProwJobs to test anything that runs on Kubernetes (or Kubernetes itself).
+* [label_sync](/label_sync) maintains GitHub labels across orgs and repos based on yaml configuration.
 
 ## Handle scale
 

prow/plugins/README.md

@@ -44,3 +44,7 @@ external_plugins:
   - name: cherrypick
     # No events specified implies all event types.
 ```
+
+## How to test a plugin
+
+See [`build_test_update.md`](/prow/build_test_update.md#How-to-test-a-plugin).