Add Build Name Setter to Builders

The Build Name Setter allows for the name to be updated during
the build process, allowing for dynamic values to be added
to the build-name (ex. #${BUILD_NAME}-{GIT_REVISION,length=8},
this example also leverages use of the Token Macro plugin)

Story: 2000560

Change-Id: I3f75051383ca89caa1283440e3581f14cee62f44

jenkins_jobs/modules/builders.py

@@ -2989,3 +2989,45 @@ def docker_build_publish(parse, xml_parent, data):
         data.get('skip-', False)).lower()
     XML.SubElement(db, 'dockerfilePath').text = str(
         data.get('file-path', ''))
+
+
+def build_name_setter(parser, xml_parent, data):
+    """yaml: build-name-setter
+    Define Build Name Setter options which allows your build name to be
+    updated during the build process.
+    Requires the Jenkins :jenkins-wiki:`Build Name Setter Plugin
+    <Build+Name+Setter+Plugin>`.
+
+    :arg str name: Filename to use for Build Name Setter, only used if
+        file bool is true. (default 'version.txt')
+    :arg str template: Macro Template string, only used if macro
+        bool is true. (default '#${BUILD_NUMBER}')
+    :arg bool file: Read from named file (default false)
+    :arg bool macro: Read from macro template (default false)
+    :arg bool macro-first: Insert macro first (default false)
+
+    File Example:
+
+    .. literalinclude::
+        /../../tests/builders/fixtures/build-name-setter001.yaml
+       :language: yaml
+
+    Macro Example:
+
+    .. literalinclude::
+        /../../tests/builders/fixtures/build-name-setter002.yaml
+       :language: yaml
+    """
+    build_name_setter = XML.SubElement(
+        xml_parent,
+        'org.jenkinsci.plugins.buildnameupdater.BuildNameUpdater')
+    XML.SubElement(build_name_setter, 'buildName').text = data.get(
+        'name', 'version.txt')
+    XML.SubElement(build_name_setter, 'macroTemplate').text = data.get(
+        'template', '#${BUILD_NUMBER}')
+    XML.SubElement(build_name_setter, 'fromFile').text = str(
+        data.get('file', False)).lower()
+    XML.SubElement(build_name_setter, 'fromMacro').text = str(
+        data.get('macro', False)).lower()
+    XML.SubElement(build_name_setter, 'macroFirst').text = str(
+        data.get('macro-first', False)).lower()

tests/builders/fixtures/build-name-setter001.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <builders>
+    <org.jenkinsci.plugins.buildnameupdater.BuildNameUpdater>
+      <buildName>version.txt</buildName>
+      <macroTemplate>#${BUILD_NUMBER}</macroTemplate>
+      <fromFile>true</fromFile>
+      <fromMacro>false</fromMacro>
+      <macroFirst>false</macroFirst>
+    </org.jenkinsci.plugins.buildnameupdater.BuildNameUpdater>
+  </builders>
+</project>

tests/builders/fixtures/build-name-setter001.yaml

@@ -0,0 +1,4 @@
+builders:
+      - build-name-setter:
+          name: 'version.txt'
+          file: true

tests/builders/fixtures/build-name-setter002.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <builders>
+    <org.jenkinsci.plugins.buildnameupdater.BuildNameUpdater>
+      <buildName>version.txt</buildName>
+      <macroTemplate>#${BUILD_NUMBER}</macroTemplate>
+      <fromFile>false</fromFile>
+      <fromMacro>true</fromMacro>
+      <macroFirst>false</macroFirst>
+    </org.jenkinsci.plugins.buildnameupdater.BuildNameUpdater>
+  </builders>
+</project>

tests/builders/fixtures/build-name-setter002.yaml

@@ -0,0 +1,4 @@
+builders:
+      - build-name-setter:
+          template: '#${BUILD_NUMBER}'
+          macro: true