Expand and edit the recipe user guide

In this change:
 - Change the overall subheading hierarchy.
   Previously all sections were sub-sections of "intro"
 - Remove the TOC in the intro section, there's already a TOC above
 - Rephrase some headings
 - Add a few sentences to clarify some parts
 - Plus minor capitalization/punctuation/space editing

This doesn't add anything from old_user_guide.md, although I'd like
to do that in a separate CL.

Bug: 1147490
Change-Id: If97e3647f885526ec18bca6de87347a2c9a6b0e3
Reviewed-on: https://chromium-review.googlesource.com/c/infra/luci/recipes-py/+/2529234
Commit-Queue: Quinten Yearsley <qyearsley@chromium.org>
Reviewed-by: Andrii Shyshkalov <tandrii@google.com>
Reviewed-by: Yiwei Zhang <yiwzhang@google.com>
Auto-Submit: Quinten Yearsley <qyearsley@chromium.org>
1 file changed
tree: 6b1a06b59953edf222bfadf11c0ec5ad9f07cac9
  1. .gitattributes
  2. .gitignore
  3. .style.yapf
  4. .vpython
  10. README.md
  11. README.recipes.md
  12. codereview.settings
  13. doc/
  14. infra/
  15. misc/
  16. recipe_engine/
  17. recipe_modules/
  18. recipe_proto/
  19. recipes.py
  20. recipes/
  21. unittests/


Recipes are a domain-specific language (embedded in Python) for specifying sequences of subprocess calls in a cross-platform and testable way.

They allow writing build flows which integrate with the rest of LUCI.

Documentation for the recipe engine (including this file!). Take a look at the user guide for some hints on how to get started. See the implementation details doc for more detailed implementation information about the recipe engine.


  • Sign the Google CLA.
  • Make sure your user.email and user.name are configured in git config.

Run the following to setup the code review tool and create your first review:

# Get `depot_tools` in $PATH if you don't have it
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/src/depot_tools
export PATH="$PATH:$HOME/src/depot_tools"

# Check out the recipe engine repo
git clone https://chromium.googlesource.com/infra/luci/recipes-py $HOME/src/recipes-py

# make your change
cd $HOME/src/recipes-py
git new-branch cool_feature
# hack hack
git commit -a -m "This is awesome"

# This will ask for your Google Account credentials.
git cl upload -s -r joe@example.com
# Wait for approval over email.
# Click "Submit to CQ" button or ask reviewer to do it for you.
# Wait for the change to be tested and landed automatically.

Use git cl help and git cl help <cmd> for more details.