Merge "Add enqueue reporter action"

doc/source/user/config.rst

@@ -247,6 +247,11 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       Three replacement fields are available ``status_url``, ``pipeline`` and
       ``change``.
 
+   .. attr:: enqueue-message
+
+      The introductory text in reports when an item is enqueued.
+      Empty by default.
+
    .. attr:: merge-failure-message
       :default: Merge failed.
 
@@ -364,11 +369,18 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       then the ``failure`` reporters will be used to notify of
       unsuccessful merges.
 
+   .. attr:: enqueue
+
+      These reporters describe what Zuul should do when an item is
+      enqueued into the pipeline.  This may be used to indicate to a
+      system or user that Zuul is aware of the triggering event even
+      though it has not evaluated whether any jobs will run.
+
    .. attr:: start
 
-      These reporters describe what Zuul should do when a change is
-      added to the pipeline.  This can be used, for example, to reset
-      a previously reported result.
+      These reporters describe what Zuul should do when jobs start
+      running for an item in the pipeline.  This can be used, for
+      example, to reset a previously reported result.
 
    .. attr:: disabled
 

releasenotes/notes/add-enqueue-reporter-action-4340b917c1cfca37.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Added the :attr:`pipeline.enqueue` reporter action so that
+    reporters may be run when an item is enqueued into a pipeline.

zuul/configloader.py

@@ -1119,6 +1119,7 @@ class ProjectParser(object):
 class PipelineParser(object):
     # A set of reporter configuration keys to action mapping
     reporter_actions = {
+        'enqueue': 'enqueue_actions',
         'start': 'start_actions',
         'success': 'success_actions',
         'failure': 'failure_actions',
@@ -1188,8 +1189,8 @@ class PipelineParser(object):
         pipeline['require'] = self.getDriverSchema('require')
         pipeline['reject'] = self.getDriverSchema('reject')
         pipeline['trigger'] = vs.Required(self.getDriverSchema('trigger'))
-        for action in ['start', 'success', 'failure', 'merge-failure',
-                       'disabled']:
+        for action in ['enqueue', 'start', 'success', 'failure',
+                       'merge-failure', 'disabled']:
             pipeline[action] = self.getDriverSchema('reporter')
         return vs.Schema(pipeline)
 
@@ -1216,6 +1217,7 @@ class PipelineParser(object):
         pipeline.footer_message = conf.get('footer-message', "")
         pipeline.start_message = conf.get('start-message',
                                           "Starting {pipeline.name} jobs.")
+        pipeline.enqueue_message = conf.get('enqueue-message', "")
         pipeline.dequeue_on_new_patchset = conf.get(
             'dequeue-on-new-patchset', True)
         pipeline.ignore_dependencies = conf.get(

zuul/manager/__init__.py

@@ -150,6 +150,15 @@ class PipelineManager(object):
                 return True
         return False
 
+    def reportEnqueue(self, item):
+        if not self.pipeline._disabled:
+            self.log.info("Reporting enqueue, action %s item %s" %
+                          (self.pipeline.enqueue_actions, item))
+            ret = self.sendReport(self.pipeline.enqueue_actions, item)
+            if ret:
+                self.log.error("Reporting item enqueued %s received: %s" %
+                               (item, ret))
+
     def reportStart(self, item):
         if not self.pipeline._disabled:
             self.log.info("Reporting start, action %s item %s" %
@@ -339,6 +348,9 @@ class PipelineManager(object):
             item.live = live
             self.reportStats(item)
             item.quiet = quiet
+            if not item.reported_enqueue:
+                self.reportEnqueue(item)
+                item.reported_enqueue = True
             self.enqueueChangesBehind(change, event, quiet,
                                       ignore_requirements, change_queue)
             zuul_driver = self.sched.connections.drivers['zuul']

zuul/model.py

@@ -258,6 +258,7 @@ class Pipeline(object):
         self.merge_failure_message = None
         self.success_message = None
         self.footer_message = None
+        self.enqueue_message = None
         self.start_message = None
         self.post_review = False
         self.dequeue_on_new_patchset = True
@@ -267,6 +268,7 @@ class Pipeline(object):
         self.relative_priority_queues = {}
         self.precedence = PRECEDENCE_NORMAL
         self.triggers = []
+        self.enqueue_actions = []
         self.start_actions = []
         self.success_actions = []
         self.failure_actions = []
@@ -285,6 +287,7 @@ class Pipeline(object):
     @property
     def actions(self):
         return (
+            self.enqueue_actions +
             self.start_actions +
             self.success_actions +
             self.failure_actions +
@@ -2123,6 +2126,7 @@ class QueueItem(object):
         self.enqueue_time = None
         self.dequeue_time = None
         self.reported = False
+        self.reported_enqueue = False
         self.reported_start = False
         self.quiet = False
         self.active = False  # Whether an item is within an active window

zuul/reporter/__init__.py

@@ -99,6 +99,7 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
 
     def _getFormatter(self):
         format_methods = {
+            'enqueue': self._formatItemReportEnqueue,
             'start': self._formatItemReportStart,
             'success': self._formatItemReportSuccess,
             'failure': self._formatItemReportFailure,
@@ -125,6 +126,17 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
 
         return ret
 
+    def _formatItemReportEnqueue(self, item, with_jobs=True):
+        status_url = get_default(self.connection.sched.config,
+                                 'web', 'status_url', '')
+        if status_url:
+            status_url = item.formatUrlPattern(status_url)
+
+        return item.pipeline.enqueue_message.format(
+            pipeline=item.pipeline.getSafeAttributes(),
+            change=item.change.getSafeAttributes(),
+            status_url=status_url)
+
     def _formatItemReportStart(self, item, with_jobs=True):
         status_url = get_default(self.connection.sched.config,
                                  'web', 'status_url', '')