Add/edit README files for infra/recipes

Bug: skia:6473
Change-Id: I050df47a5a3f633263f0ca6258e83e96b78d7957
Reviewed-on: https://skia-review.googlesource.com/13123
Commit-Queue: Eric Boren <borenet@google.com>
Reviewed-by: Stephan Altmueller <stephana@google.com>
Reviewed-by: Mike Klein <mtklein@chromium.org>
Reviewed-by: Kevin Lubick <kjlubick@google.com>
Reviewed-by: Ben Wagner <benjaminwagner@google.com>

3 files changed, 135 insertions, 18 deletions

diff --git a/infra/bots/README.md b/infra/bots/README.md
index 9f184aaadc..e7cbe7fcc1 100644
--- a/infra/bots/README.md
+++ b/infra/bots/README.md
@@ -1,18 +1,94 @@
-Skia Buildbot Scripts
-=====================
+Skia Infrastructure
+===================
 
-The scripts in this directory are ported from Skia's buildbot recipes and are
-intended to run as standalone Python scripts either locally or via Swarming.
+This directory contains infrastructure elements.
 
-How to Run
-----------
 
-The scripts can be run by hand, eg:
+Tasks and Jobs
+--------------
 
-$ cd infra/bots
-$ python compile_skia.py Build-Ubuntu-GCC-x86_64-Debug ../../out
+Files in this directory define a DAG of tasks which run at every Skia commit. A
+task is a small, self-contained unit which runs via Swarming on a machine in the
+pool. Tasks may be chained together, eg. one task to compile test binaries and
+another to actually run them.
 
-Or, you can run the scripts via Swarming:
+Jobs are collections of related tasks which help define sub-sections of the DAG,
+for example, to be used as try jobs. Each job is defined as an entry point into
+the DAG.
+
+The tasks.json file in this directory is the master list of tasks and jobs for
+the repo. Note that tasks.json is NEVER edited by hand but generated via
+gen_task.go and the input files enumerated below. The
+[Task Scheduler](https://skia.googlesource.com/buildbot/+/master/task_scheduler/README.md)
+reads the tasks.json file at each commit to determine which jobs to run. For
+convenience, gen_tasks.go is provided to generate tasks.json and also to test it
+for correct syntax and detecting cycles and orphaned tasks. Always edit
+gen_tasks.go or one of the following input JSON files, rather than tasks.json
+itself:
+
+  * android_map.json - Maps human-friendly names of Android devices to their
+      device codename and desired OS version. Edit this file when adding a new
+      type of Android device or updating the desired OS version.
+  * cfg.json - Basic configuration information for gen_tasks.go.
+  * gpu_map.json - Maps human-friendly names of GPUs to an appropriate Swarming
+      dimension, typically the PCI ID of the GPU. Edit this file when adding a
+      new GPU.
+  * jobs.json - The master list of all jobs to run. Edit this to add or remove
+      bots.
+
+Whenever gen_tasks.go, any of the above JSON files, or assets are changed, you
+need to run gen_tasks.go to regenerate tasks.json:
+
+	$ go run infra/bots/gen_tasks.go
+
+There is also a test mode which performs sanity-checks and verifies that
+tasks.json is unchanged:
+
+	$ go run infra/bots/gen_tasks.go --test
+
+
+Recipes
+-------
+
+Recipes are the framework used by Skia's infrastructure to perform work inside
+of Swarming tasks. The main elements are:
+
+  * recipes.py - Used for running and testing recipes.
+  * recipes - These are the entry points for each type of task, eg. compiling
+      or running tests.
+  * recipe_modules - Shared modules which are used by recipes.
+  * .recipe_deps - Recipes and modules may depend on modules from other repos.
+      The recipes.py script automatically syncs those dependencies in this
+      directory.
+
+
+Isolate Files
+-------------
+
+These files determine which parts of the repository are transferred to the bot
+when a Swarming task is triggered. The
+[Isolate tool](https://github.com/luci/luci-py/tree/master/appengine/isolate/doc)
+hashes each file and will upload any new/changed files. Bots maintain a cache so
+that they can efficiently download only the files they don't have.
+
+
+Assets
+------
+
+Artifacts used by the infrastructure are versioned here, along with scripts for
+recreating/uploading/downloading them. See the README in that directory for more
+information. Any time an asset used by the bots changes, you need to re-run
+gen_tasks.go.
+
+
+Tools
+-----
+
+Assorted other infrastructure-related tools, eg. isolate and CIPD binaries.
+
+
+CT
+--
+
+Helpers for running Skia tasks in Cluster Telemetry.
 
-$ isolate archive --isolate-server https://isolateserver.appspot.com/ -i infra/bots/compile_skia.isolate -s ../compile-skia.isolated --verbose --config-variable BUILDER_NAME=Build-Ubuntu-GCC-x86_64-Debug
-$ swarming.py run --swarming https://chromium-swarm.appspot.com --isolate-server https://isolateserver.appspot.com --dimension os Ubuntu --dimension pool Skia --task-name compile-skia --io-timeout=3600 --hard-timeout=3600 ../compile-skia.isolated
diff --git a/infra/bots/recipe_modules/README.md b/infra/bots/recipe_modules/README.md
index 05ad2cc76b..3ddf5ab248 100644
--- a/infra/bots/recipe_modules/README.md
+++ b/infra/bots/recipe_modules/README.md
@@ -1,11 +1,31 @@
 Skia Recipe Modules
 ===================
 
-This directory contains recipe modules designed to be used by recipes. They
-are all Skia-specific and some are interrelated:
+This directory contains recipe modules designed to be used by recipes (see
+infra/bots/recipes). They are all Skia-specific and some are interrelated:
 
-  * vars - Common variables used by Skia recipes.
-  * run - Utilities for running commands. Depends on vars.
-  * flavor - Run meta-commands for various platforms. Depends on vars and run.
-  * skia - Main module for Skia recipes. Depends on vars, run, and flavor.
+  * builder_name_schema - Helps to derive expected behavior from task (formerly
+      builder) names.
+  * core - Use as a starting point for most recipes: runs setup and sync steps.
+  * ct - Shared Cluster Telemetry utilities.
+  * flavor - Allows the caller to specify a high-level command to run, leaving
+      the platform-specific details to be handled by the specific flavor
+      module.
+  * infra - Shared infrastructure-related utilities.
+  * run - Utilities for running commands.
   * swarming - Utilities for running Swarming tasks.
+  * vars - Common global variables used by Skia recipes/modules.
+
+When you change a recipe module, you generally need to re-train the simulation
+test:
+
+	$ python infra/bots/recipes.py simulation_test train
+
+Each recipe module contains a few files:
+
+  * api.py - This is the meat of the module.
+  * \_\_init\_\_.py - Contains a single DEPS variable, indicating the other
+      recipe modules on which this module depends.
+  * example.py - Optional, this file contains examples which demonstrate how to
+      use the module and should contain enough tests to achieve 100% coverage
+      for the module. The tests are run using the simulation_test command above.
diff --git a/infra/bots/recipes/README.md b/infra/bots/recipes/README.md
new file mode 100644
index 0000000000..a9c4c6ab43
--- /dev/null
+++ b/infra/bots/recipes/README.md
@@ -0,0 +1,21 @@
+Skia Recipes
+============
+
+These are the top-level scripts which run inside of Swarming tasks to perform
+all of Skia's automated testing.
+
+To run a recipe locally:
+
+	$ python infra/bots/recipes.py run --workdir=/tmp/<workdir> <recipe name without .py> key1=value1 key2=value2 ...
+
+Each recipe may have its own required properties which must be entered as
+key/value pairs in the command.
+
+When you change a recipe, you generally need to re-train the simulation test:
+
+	$ python infra/bots/recipes.py simulation_test train
+
+The simulation_test generates expectations files for the tests contained within
+each recipe which illustrate which steps would run, given a particular set of
+inputs. Pay attention to the diffs in these files when making changes to ensure
+that your change has the intended effect.