From 6d7927520ed96bf2f494b0e0e840b71e6ceae7fa Mon Sep 17 00:00:00 2001 From: Anil Belur Date: Thu, 7 Sep 2017 00:11:22 +1000 Subject: [PATCH] Update JJB best practices Using single quotes around variables. Update parameter passing section to avoid using `!include-raw`. Also remove single quotes around examples where its not required. Change-Id: I176c861a90fcea29c3fd77308287f241e9f26a6c Signed-off-by: Anil Belur --- docs/best-practices.rst | 47 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/docs/best-practices.rst b/docs/best-practices.rst index d9dde749..534031a5 100644 --- a/docs/best-practices.rst +++ b/docs/best-practices.rst @@ -210,16 +210,26 @@ We recommend avoiding using method 1 (Pass JJB variables) into shell scripts and instead always use method 2 (Enviornment variables). This makes troubleshooting JJB errors easier and does not require escaping curly braces. -This method requires 2 steps: +This method requires 3 steps: + +1) Declare a parameter section or inject the variable as properties-content. +2) Invoke the shell script with `include-raw-escape` instead of `include-raw`. +3) Use the shell variable in shell script. -1) Declare a parameter section -2) Use the parameter in shell script The benefit of this method is that parameters will always be at the top of the job page and when clicking the Build with Parameters button in Jenkins we can see the parameters before running the job. We can review the parameters retro-actively by visiting the job parameters page -``job/lastSuccessfulBuild/parameters/``. +``job/lastSuccessfulBuild/parameters/``. Injecting variables as +properties-content makes the variable local to the specific macro, while +declaring it as parameter makes the variable global. + +.. note:: + + When a macro which invokes a shell script has no JJB parameters defined + `!include-raw-escape` will insert extra curly braces, in such cases its + recommended to use `!include-raw`. Usage of config-file-provider ----------------------------- @@ -238,8 +248,8 @@ ship-logs example: builders: - config-file-provider: files: - - file-id: 'jenkins-log-archives-settings' - variable: 'SETTINGS_FILE' + - file-id: jenkins-log-archives-settings + variable: SETTINGS_FILE - shell: !include-raw: - ../shell/logs-get-credentials.sh - shell: !include-raw: @@ -279,8 +289,8 @@ Example: - triggers: - lf-infra-github-pr-trigger: - trigger-phrase: '^remerge$' - status-context: 'JJB Merge' + trigger-phrase: ^remerge$ + status-context: JJB Merge permit-all: false github-hooks: true github-org: '{github-org}' @@ -289,3 +299,24 @@ Example: In the above example note the use of underscores in `github_pr_admin_list` and `github_pr_admin_list`. + +Using single quotes around variables +------------------------------------ + +Its recommended to use single quotes around JJB variables '{variable}-field' +during variable substitution or when using a variable in a string field, in +other cases its recommended to drop the single quotes. + +Example: + +.. code-block:: yaml + + - builder: + name: lf-user-logs + builders: + - inject: + properties-content: | + 'HOME={user-home}' + - build-file: + settings: '{settings-file}' + file-version: '{file-version}' -- 2.16.6