Chore: Upgrade Jenkins-job-builder to 6.3.0

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

diff --git a/docs/best-practices.rst b/docs/best-practices.rst
index a9d4d20..199422a 100644 (file)
--- a/docs/best-practices.rst
+++ b/docs/best-practices.rst
@@ -104,6 +104,38 @@ declaring it as parameter makes the variable global.
     `!include-raw-escape` will insert extra curly braces, in such cases its
     recommended to use `!include-raw`.
 
+.. _shell-scripts:
+
+Shell scripts
+=============
+
+When developing shell scripts for JJB we recommend to create shell scripts as
+a separate file instead of inlining in YAML. This way we can ensure that the
+ShellCheck linter can catch potential issues with the scripts.
+
+When writing the script itself, we recommend to redeclare all expected
+inputs at the top of the file using lowercase variable names before setting
+``set -u`` after the inputs section. This ensures that all variables the
+script expects are at the top of the file which is useful for others to review
+and debug the script at a later stage. The ``set -u`` configuration before the
+start of the script code ensures that we catch any of these undeclared
+variables at the top of the file.
+
+Example:
+
+.. code-block:: bash
+
+   #!/bin/bash
+
+   # Inputs
+   tox_dir="${TOX_DIR:-$WORKSPACE}"
+   tox_envs="${TOX_ENVS:-}"
+
+   # Script start
+   set -eux -o pipefail
+
+   # ... script code goes here
+
 Usage of config-file-provider
 =============================
 
@@ -126,7 +158,6 @@ ship-logs example:
           - shell: !include-raw:
               - ../shell/logs-get-credentials.sh
           - shell: !include-raw:
-              - ../shell/lftools-install.sh
               - ../shell/logs-deploy.sh
           - shell: !include-raw:
               - ../shell/logs-clear-credentials.sh
@@ -140,15 +171,17 @@ complete running via the logs-clear-credentials.sh script. This script contains
 3 basic steps:
 
 1. Provide credentials via config-file-provider
-2. Run the build scripts in this case lftools-install.sh and logs-deploy.sh
+2. Run logs-deploy.sh
 3. Remove credentials provided by config-file-provider
 
+.. _preserve-variable-refs:
+
 Preserving Objects in Variable References
 =========================================
 
 JJB has an option to preserve a data structure object when you want to pass
 it to a template.
-https://docs.openstack.org/infra/jenkins-job-builder/definition.html#variable-references
+https://jenkins-job-builder.readthedocs.io/en/latest/definition.html#variable-references
 
 One thing that is not explicitly covered is the format of the variable name
 that you pass the object to. When you use the `{obj:key}` notation to preserve
@@ -160,18 +193,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_allowlist``,
+``github_pr_admin_list``, and ``github_included_regions``.
 
 Using single quotes around variables
 ====================================
@@ -303,7 +328,7 @@ In this case there is a default '{message}' set in the
 If we do not declare a default in the :ref:`job-template <job-template>` then
 JJB will fallback to checking the "defaults configuration".
 
-This means that the precendence of defaults is as follows:
+This means that the precedence of defaults is as follows:
 
 1. User-provided
 2. Job Template
@@ -337,12 +362,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 precedence. Global JJB should strive to be purely a
+job-template and macro library for downstream consumers.
+
 Final thoughts
 --------------