Fix API breakage caused by OS Plugin version scan

[releng/global-jjb.git] / docs / best-practices.rst

diff --git a/docs/best-practices.rst b/docs/best-practices.rst
index a9d4d20..c298fda 100644 (file)
--- a/docs/best-practices.rst
+++ b/docs/best-practices.rst
@@ -143,6 +143,8 @@ complete running via the logs-clear-credentials.sh script. This script contains
 2. Run the build scripts in this case lftools-install.sh and logs-deploy.sh
 3. Remove credentials provided by config-file-provider
 
+.. _preserve-variable-refs:
+
 Preserving Objects in Variable References
 =========================================
 
@@ -160,18 +162,10 @@ Example:
 
 .. code-block:: yaml
 
-    - triggers:
-       - lf-infra-github-pr-trigger:
-           trigger-phrase: ^remerge$
-           status-context: JJB Merge
-           permit-all: false
-           github-hooks: true
-           github-org: '{github-org}'
-           github_pr_whitelist: '{obj:github_pr_whitelist}'
-           github_pr_admin_list: '{obj:github_pr_admin_list}'
+   .. literalinclude:: _static/github-pr-trigger.example
 
-In the above example note the use of underscores in `github_pr_admin_list` and
-`github_pr_admin_list`.
+In the above example note the use of underscores in ``github_pr_whitelist``,
+``github_pr_admin_list``, and ``github_included_regions``.
 
 Using single quotes around variables
 ====================================
@@ -337,12 +331,18 @@ variable. JJB will fill in whatever is in the defaults configuration.
 
 Variable expansion order of precedence seems to be:
 
-1. project section definition
-2. job-template variable definition
-3. defaults.yaml variable definition
+1. job-group section definition
+2. project section definition
+3. job-template variable definition
+4. defaults.yaml variable definition
 
 .. note:: Defaults set variables in job-templates and are NOT used in Macros.
 
+global-jjb should not provide job-group definitions and leave it up to users of
+global-jjb to create their own as a job-group as a variable defined in a job
+group the highest precendence. Global JJB should strive to be purely a
+job-template and macro library for downstream consumers.
+
 Final thoughts
 --------------