Support for more options in gerrit plugin and doc cleanup.

Following options are added -
* Other jobs on which this job depends
* Notification Level
* Unsuccessful Message File
* Silent Start Mode

Gerrit docstring cleanup for better indentation.

Change-Id: I2d0988973dcdd7ff32e7cdcd2c2676da3235e7fc

jenkins_jobs/modules/triggers.py

@@ -32,9 +32,10 @@ Example::
 
 import six
 import xml.etree.ElementTree as XML
-from jenkins_jobs.errors import JenkinsJobsException
 import jenkins_jobs.modules.base
 from jenkins_jobs.modules import hudson_model
+from jenkins_jobs.errors import (InvalidAttributeError,
+                                 JenkinsJobsException)
 import logging
 import re
 try:
@@ -248,13 +249,11 @@ def gerrit(parser, xml_parent, data):
 
                * **approval-value** -- Approval value for the comment added.
          * **comment-added-contains-event** (`dict`) -- Trigger on comment
-                                                        added contains
-                                                        Regular Expression.
+           added contains Regular Expression.
 
            :Comment added contains:
                * **comment-contains-value** (`str`) -- Comment contains
-                                                       Regular Expression
-                                                       value.
+                 Regular Expression value.
 
     :arg bool trigger-on-patchset-uploaded-event: Trigger on patchset upload.
 
@@ -316,6 +315,8 @@ def gerrit(parser, xml_parent, data):
     :arg str successful-message: Message to leave on success (default '')
     :arg str unstable-message: Message to leave when unstable (default '')
     :arg str notbuilt-message: Message to leave when not built (default '')
+    :arg str failure-message-file: Sets the filename within the workspace from
+        which to retrieve the unsuccessful review message. (optional)
     :arg list projects: list of projects to match
 
       :Project: * **project-compare-type** (`str`) --  ''PLAIN'', ''ANT'' or
@@ -363,6 +364,9 @@ def gerrit(parser, xml_parent, data):
         messages etc. If other non-silent jobs are triggered by the same
         Gerrit event as this job, the result of this job's build will not be
         counted in the end result of the other jobs. (default false)
+    :arg bool silent-start: Sets silent start mode to on or off. When silent
+        start mode is on there will be no 'build started' messages sent back
+        to Gerrit. (default false)
     :arg bool escape-quotes: escape quotes in the values of Gerrit change
         parameters (default true)
     :arg bool no-name-and-email: Do not pass compound 'name and email'
@@ -371,6 +375,15 @@ def gerrit(parser, xml_parent, data):
         e.g. commit message, should be as human readable or not. If false,
         those parameters are Base64 encoded to keep environment variables
         clean. (default false)
+    :arg str dependency-jobs: All jobs on which this job depends. If a commit
+        should trigger both a dependency and this job, the dependency will be
+        built first. Use commas to separate job names. Beware of cyclic
+        dependencies. (optional)
+    :arg str notification-level: Defines to whom email notifications should be
+        sent. This can either be nobody ('NONE'), the change owner ('OWNER'),
+        reviewers and change owner ('OWNER_REVIEWERS'), all interested users
+        i.e. owning, reviewing, watching, and starring ('ALL') or server
+        default ('SERVER_DEFAULT'). (default 'SERVER_DEFAULT')
     :arg bool dynamic-trigger-enabled: Enable/disable the dynamic trigger
         (default false)
     :arg str dynamic-trigger-url: if you specify this option, the Gerrit
@@ -470,12 +483,26 @@ def gerrit(parser, xml_parent, data):
     build_gerrit_skip_votes(gtrig, data)
     XML.SubElement(gtrig, 'silentMode').text = str(
         data.get('silent', False)).lower()
+    XML.SubElement(gtrig, 'silentStartMode').text = str(
+        data.get('silent-start', False)).lower()
     XML.SubElement(gtrig, 'escapeQuotes').text = str(
         data.get('escape-quotes', True)).lower()
     XML.SubElement(gtrig, 'noNameAndEmailParameters').text = str(
         data.get('no-name-and-email', False)).lower()
     XML.SubElement(gtrig, 'readableMessage').text = str(
         data.get('readable-message', False)).lower()
+    XML.SubElement(gtrig, 'dependencyJobsNames').text = str(
+        data.get('dependency-jobs', ''))
+    notification_levels = ['NONE', 'OWNER', 'OWNER_REVIEWERS', 'ALL',
+                           'SERVER_DEFAULT']
+    notification_level = data.get('notification-level', 'SERVER_DEFAULT')
+    if notification_level not in notification_levels:
+        raise InvalidAttributeError('notification-level', notification_level,
+                                    notification_levels)
+    if notification_level == 'SERVER_DEFAULT':
+        XML.SubElement(gtrig, 'notificationLevel').text = ''
+    else:
+        XML.SubElement(gtrig, 'notificationLevel').text = notification_level
     XML.SubElement(gtrig, 'dynamicTriggerConfiguration').text = str(
         data.get('dynamic-trigger-enabled', False))
     XML.SubElement(gtrig, 'triggerConfigURL').text = str(
@@ -519,6 +546,8 @@ def gerrit(parser, xml_parent, data):
         data.get('unstable-message', ''))
     XML.SubElement(gtrig, 'buildNotBuiltMessage').text = str(
         data.get('notbuilt-message', ''))
+    XML.SubElement(gtrig, 'buildUnsuccessfulFilepath').text = str(
+        data.get('failure-message-file', ''))
     XML.SubElement(gtrig, 'customUrl').text = str(data.get('custom-url', ''))
     XML.SubElement(gtrig, 'serverName').text = str(
         data.get('server-name', '__ANY__'))

tests/triggers/fixtures/gerrit001.xml

@@ -28,9 +28,12 @@
         <onNotBuilt>true</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>false</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
       <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
       <allowTriggeringUnreviewedPatches>false</allowTriggeringUnreviewedPatches>
@@ -45,6 +48,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>__ANY__</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/triggers/fixtures/gerrit002.xml

@@ -32,9 +32,12 @@
         <onNotBuilt>true</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>false</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
       <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
       <allowTriggeringUnreviewedPatches>false</allowTriggeringUnreviewedPatches>
@@ -49,6 +52,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>__ANY__</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/triggers/fixtures/gerrit003.xml

@@ -48,9 +48,12 @@
         <onNotBuilt>true</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>false</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
       <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
       <allowTriggeringUnreviewedPatches>false</allowTriggeringUnreviewedPatches>
@@ -65,6 +68,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>__ANY__</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/triggers/fixtures/gerrit004.xml

@@ -38,9 +38,12 @@
         <onNotBuilt>true</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>true</silentStartMode>
       <escapeQuotes>false</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames>job1, job2</dependencyJobsNames>
+      <notificationLevel>ALL</notificationLevel>
       <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
       <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
       <allowTriggeringUnreviewedPatches>true</allowTriggeringUnreviewedPatches>
@@ -60,6 +63,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath>path/to/filename</buildUnsuccessfulFilepath>
       <customUrl/>
       <serverName>my-server</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/triggers/fixtures/gerrit004.yaml

@@ -28,9 +28,13 @@ triggers:
           unstable: true
           notbuilt: true
       silent: false
+      silent-start: true
       escape-quotes: false
       no-name-and-email: false
+      dependency-jobs: 'job1, job2'
+      notification-level: ALL
       dynamic-trigger-enabled: true
       dynamic-trigger-url: http://myhost/mytrigger
       trigger-for-unreviewed-patches: true
       server-name: my-server
+      failure-message-file: path/to/filename

tests/triggers/fixtures/gerrit005.xml

@@ -28,9 +28,12 @@
         <onNotBuilt>false</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>true</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>False</dynamicTriggerConfiguration>
       <triggerConfigURL/>
       <allowTriggeringUnreviewedPatches>false</allowTriggeringUnreviewedPatches>
@@ -46,6 +49,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>__ANY__</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/triggers/fixtures/gerrit006.xml

@@ -28,9 +28,12 @@
         <onNotBuilt>true</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>false</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>true</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
       <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
       <allowTriggeringUnreviewedPatches>false</allowTriggeringUnreviewedPatches>
@@ -44,6 +47,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>__ANY__</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/triggers/fixtures/gerrit007.xml

@@ -38,9 +38,12 @@
         <onNotBuilt>true</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>false</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
       <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
       <allowTriggeringUnreviewedPatches>true</allowTriggeringUnreviewedPatches>
@@ -56,6 +59,7 @@
       <buildSuccessfulMessage/>
       <buildUnstableMessage/>
       <buildNotBuiltMessage/>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>my-server</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>

tests/yamlparser/fixtures/complete001.xml

@@ -71,9 +71,12 @@
         <onNotBuilt>false</onNotBuilt>
       </skipVote>
       <silentMode>false</silentMode>
+      <silentStartMode>false</silentStartMode>
       <escapeQuotes>true</escapeQuotes>
       <noNameAndEmailParameters>false</noNameAndEmailParameters>
       <readableMessage>false</readableMessage>
+      <dependencyJobsNames/>
+      <notificationLevel/>
       <dynamicTriggerConfiguration>False</dynamicTriggerConfiguration>
       <triggerConfigURL/>
       <allowTriggeringUnreviewedPatches>false</allowTriggeringUnreviewedPatches>
@@ -95,6 +98,7 @@
       <buildSuccessfulMessage>Success message.</buildSuccessfulMessage>
       <buildUnstableMessage>Unstable message.</buildUnstableMessage>
       <buildNotBuiltMessage>Not built message.</buildNotBuiltMessage>
+      <buildUnsuccessfulFilepath/>
       <customUrl/>
       <serverName>__ANY__</serverName>
     </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>