recipes/README.md

# recipes

This directory contains scripts which run on LUCI builders. These scripts take
the form of [recipes][1], a command-execution DSL. The recipes in this repo live
in the `recipes` and `recipe_modules` subdirectories.

[1]: https://chromium.googlesource.com/infra/luci/recipes-py

## Quick How-To-Modify-Recipes

 1. Make your changes to the various `recipes` or `recipe_modules` that you
    need.
 1. Run the simulator by running `./recipes.py test train`.

    If you want to update a single recipe, run `./recipes.py test train --filter=<recipe-name>`.

    This will run through all the simulation inputs generated by the recipes'
    GenTests methods, executing the recipe code for each one, using the
    simulation inputs to mock the output of the various steps. The list of steps
    that the recipe would have run, given that simulation's inputs, will be
    recorded as a JSON file in the recipe's `<recipe.expected>` folder.
    <recipe-name> is of the form <dir>:file.test (for example,
    pgo:full.weights identifies the 'weights' test in the file
    'recipe_modules/pgo/tests/full.py', notice the 'tests' directory is not
    included).
 1. Upload the recipe changes as well as the new expectation files.
 1. Review the expectation file diffs to make sure they're actually what you
    intended. If your CL affects many expectation files, it's STRONGLY
    recommended to make your CL change as small as possible so that it's easy
    to correlate the code change with the expectation changes.

The recipe simulator insists on 100% line coverage of the recipes. If it
complains about uncovered lines, you should add a new simulation case to the
GenTests method of the given recipe. Give it a descriptive name for what case
you're trying to cover, and give it step output values which would lead to that
case. For example `'report_bad_targets_on_compile_failure'` might have the
compile step exit with a return code of 1 and emit a JSON file containing the
bad target names. You would instruct the test in GenTests to do this, and when
the simulator runs it, it will use your supplied return code and JSON file to
simulate that step having those outputs.

Failing to train the expectations will cause the CQ to reject the patch; it will
run the simulation tests in `test` mode, which checks to see that the
expectation files match the current recipe code, but doesn't emit the new JSON
files if it finds a descrepancy.

## Recipes documentation

The recipe code in this directory (modules in `recipe_modules` and recipes in
`recipes`) have some documentation in them, in the standard Python docstring
style. You can view this documentation by reading the files. The recipe system
also has a way to generate documentation for a set of recipes. Running
`./recipes.py doc` from this directory will generate a `README.recipes.md` file.
This file may be easier to use than directly browsing the files themselves.