Revise docker-get-container-tag-script macro

Silence JJB warning by calling include-raw (not include-raw-escape)
when pulling in shell-script content; the result is the same.
Extend the documentation for the supported methods.
Add details on the contract of the shell script.

Change-Id: I6de0746653d3ceaf6df9fc63eb7aff5259f4b062
Signed-off-by: Lott, Christopher (cl778h) <cl778h@att.com>

diff --git a/docs/jjb/lf-docker-jobs.rst b/docs/jjb/lf-docker-jobs.rst
index 09abbbb..ba65b29 100644 (file)
--- a/docs/jjb/lf-docker-jobs.rst
+++ b/docs/jjb/lf-docker-jobs.rst
@@ -19,16 +19,42 @@ Macros
 lf-docker-get-container-tag
 ---------------------------
 
-Chooses a container tag to label the image based on the 'container-tag-method'
-parameter.  If container-tag-method: latest, the tag 'latest' is used.
-If container-tag-method: git-describe, the tag is obtained using
-the git describe command, which requires that the repository has a git tag.
-If container-tag-method: yaml-file, the tag is obtained using
-the yq command, which requires that the repository has a YAML file named
-'container-tag.yaml'. The script checks the docker-root directory by
-default or the directory specified by parameter container-tag-yaml-dir.
-An example file appears below. Optionally, teams can call their own script to
-handle the docker tagging differently.
+Chooses a tag to label the container image based on the
+'container-tag-method' parameter using the global-jjb script
+docker-get-container-tag.sh. Use one of the following methods:
+
+If container-tag-method: latest, the literal string 'latest' is used.
+
+If container-tag-method: git-describe, the tag is obtained using the
+git describe command on the repository, which requires that the repository
+has a git tag. For example, if the most recent tag is 'v0.48.1', this
+method yields a string like 'v0.48.1' or 'v0.48.1-25-gaee2dcb'.
+
+If container-tag-method: yaml-file, the tag is obtained from the YAML file
+'container-tag.yaml' in the docker-root directory using the top-level entry
+'tag'. Alternately specify the directory with the YAML file in parameter
+'container-tag-yaml-dir'. An example file appears next.
+
+Example container-tag.yaml file:
+
+.. code-block:: yaml
+
+   ---
+   tag: 1.0.0
+
+
+Optionally, teams can supply their own script to choose the docker
+tag. Pass the shell script path in optional configuration parameter
+'docker-get-container-tag-script' which by default is the path to
+file docker-get-container-tag.sh. The script must create the file
+'env_docker_inject.txt' in the workspace with a line that assigns a
+value to shell variable DOCKER_IMAGE_TAG, as shown next.
+
+Example env_docker_inject.txt file:
+
+.. code-block:: shell
+
+    DOCKER_IMAGE_TAG=1.0.0
 
 
 lf-docker-build
@@ -80,7 +106,7 @@ Executes a docker build task.
         (default: latest)
     :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
     :docker-build-args: Additional arguments for the docker build command.
-    :docker-get-container-tag-script: Pointer to script to handle docker tags.
+    :docker-get-container-tag-script: Path to script that chooses docker tag.
         (default: ../shell/docker-get-container-tag.sh)
     :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
@@ -151,7 +177,7 @@ Executes a docker build task and publishes the resulting images to a specified D
         one may want to provide more than 1 cron timer. No default. Use
         '@daily' to run daily or 'H H * * 0' to run weekly.
     :docker-build-args: Additional arguments for the docker build command.
-    :docker-get-container-tag-script: Pointer to script to handle docker tags.
+    :docker-get-container-tag-script: Path to script that chooses docker tag.
         (default: ../shell/docker-get-container-tag.sh)
     :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)

diff --git a/jjb/lf-docker-jobs.yaml b/jjb/lf-docker-jobs.yaml
index bc522ca..402d867 100644 (file)
--- a/jjb/lf-docker-jobs.yaml
+++ b/jjb/lf-docker-jobs.yaml
@@ -13,7 +13,7 @@
             CONTAINER_TAG_METHOD={container-tag-method}
             CONTAINER_TAG_YAML_DIR={container-tag-yaml-dir}
             DOCKER_ROOT={docker-root}
-      - shell: !include-raw-escape: "{docker-get-container-tag-script}"
+      - shell: !include-raw: "{docker-get-container-tag-script}"
       - inject:
           # Import the container tag set by this build step
           properties-file: "env_docker_inject.txt"

diff --git a/releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml b/releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml
new file mode 100644 (file)
index 0000000..5c156cf
--- /dev/null
+++ b/releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml
@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    Revise the lf-docker-get-container-tag macro to use include-raw,
+    not include-raw-escape, to silence JJB warning.
+    Improve documentation of lf-docker-get-container-tag macro.