Add support for unstable return parameter for shell builders

This continues to support the current string form for job configuration,
as well as adding a form that supports a mapping.  This mapping has two
keys: "command", containing the command to be executed (i.e. the current
string parameter); and "unstable-return", containing the exit code that
configures the exit code that should cause a build to be marked
unstable.

Change-Id: I43ecc883236bbf8fc6de7ed8992e6d90da7d48ac

jenkins_jobs/modules/builders.py

@@ -40,6 +40,8 @@ import logging
 import sys
 import xml.etree.ElementTree as XML
 
+import six
+
 from jenkins_jobs.errors import is_sequence
 from jenkins_jobs.errors import InvalidAttributeError
 from jenkins_jobs.errors import JenkinsJobsException
@@ -65,16 +67,36 @@ def shell(registry, xml_parent, data):
     """yaml: shell
     Execute a shell command.
 
+    There are two ways of configuring the builder, with a plain string to
+    execute:
+
     :arg str parameter: the shell command to execute
 
+    Or with a mapping that allows other parameters to be passed:
+
+    :arg str command: the shell command to execute
+    :arg int unstable-return:
+        the shell exit code to interpret as an unstable build result
+
     Example:
 
     .. literalinclude:: /../../tests/builders/fixtures/shell.yaml
        :language: yaml
 
+    .. literalinclude::
+        /../../tests/builders/fixtures/shell-unstable-return.yaml
+       :language: yaml
     """
     shell = XML.SubElement(xml_parent, 'hudson.tasks.Shell')
-    XML.SubElement(shell, 'command').text = data
+    if isinstance(data, six.string_types):
+        XML.SubElement(shell, 'command').text = data
+    else:
+        mappings = [
+            ('command', 'command', None),
+            ('unstable-return', 'unstableReturn', 0),
+
+        ]
+        convert_mapping_to_xml(shell, data, mappings, fail_required=True)
 
 
 def python(registry, xml_parent, data):

tests/builders/fixtures/shell-mapping.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>make test</command>
+      <unstableReturn>0</unstableReturn>
+    </hudson.tasks.Shell>
+  </builders>
+</project>

tests/builders/fixtures/shell-mapping.yaml

@@ -0,0 +1,3 @@
+builders:
+  - shell:
+      command: "make test"

tests/builders/fixtures/shell-unstable-return.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>make test</command>
+      <unstableReturn>3</unstableReturn>
+    </hudson.tasks.Shell>
+  </builders>
+</project>

tests/builders/fixtures/shell-unstable-return.yaml

@@ -0,0 +1,4 @@
+builders:
+  - shell:
+      command: "make test"
+      unstable-return: 3