Add no-jobs reporter action

This facilitates integration with the gerrit checks API (and may
prove useful for other similar APIs).  It will allow us to report
that a change has no jobs in a particular pipeline.  A Zuul
pipeline will correspond to a Gerrit check, which means we can
update the status for that check from "SCHEDULED" to "NOT_RELEVANT"
if we determine that no jobs should run for the change.  This
closes out the status of the check in Gerrit when a project is
configured to participate in a check/pipeline but no jobs are
actually configured.

Test coverage for this will be added in change
Ida0cdef682ca2ce117617eacfb67f371426a3131.

Change-Id: Ide2a332b294d7efe23601d80eeb92b5af1d4c21b

doc/source/user/config.rst

@@ -259,6 +259,11 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       fails to merge with the current state of the repository.
       Defaults to "Merge failed."
 
+   .. attr:: no-jobs-message
+
+      The introductory text in reports when an item is dequeued
+      without running any jobs.  Empty by default.
+
    .. attr:: footer-message
 
       Supplies additional information after test results.  Useful for
@@ -382,6 +387,13 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       running for an item in the pipeline.  This can be used, for
       example, to reset a previously reported result.
 
+   .. attr:: no-jobs
+
+      These reporters describe what Zuul should do when an item is
+      dequeued from a pipeline without running any jobs.  This may be
+      used to indicate to a system or user that the pipeline is not
+      relevant for a change.
+
    .. attr:: disabled
 
       These reporters describe what Zuul should do when a pipeline is

releasenotes/notes/add-no-jobs-reporter-action-a868ff8baf42c44c.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Added the :attr:`pipeline.no-jobs` reporter action so that
+    reporters may be run when an item is dequeued into a pipeline
+    without having run any jobs.

zuul/configloader.py

@@ -1124,6 +1124,7 @@ class PipelineParser(object):
         'success': 'success_actions',
         'failure': 'failure_actions',
         'merge-failure': 'merge_failure_actions',
+        'no-jobs': 'no_jobs_actions',
         'disabled': 'disabled_actions',
     }
 
@@ -1171,6 +1172,7 @@ class PipelineParser(object):
                     'failure-message': str,
                     'start-message': str,
                     'merge-failure-message': str,
+                    'no-jobs-message': str,
                     'footer-message': str,
                     'dequeue-on-new-patchset': bool,
                     'ignore-dependencies': bool,
@@ -1190,7 +1192,7 @@ class PipelineParser(object):
         pipeline['reject'] = self.getDriverSchema('reject')
         pipeline['trigger'] = vs.Required(self.getDriverSchema('trigger'))
         for action in ['enqueue', 'start', 'success', 'failure',
-                       'merge-failure', 'disabled']:
+                       'merge-failure', 'no-jobs', 'disabled']:
             pipeline[action] = self.getDriverSchema('reporter')
         return vs.Schema(pipeline)
 
@@ -1218,6 +1220,7 @@ class PipelineParser(object):
         pipeline.start_message = conf.get('start-message',
                                           "Starting {pipeline.name} jobs.")
         pipeline.enqueue_message = conf.get('enqueue-message', "")
+        pipeline.no_jobs_message = conf.get('no-jobs-message', "")
         pipeline.dequeue_on_new_patchset = conf.get(
             'dequeue-on-new-patchset', True)
         pipeline.ignore_dependencies = conf.get(

zuul/manager/__init__.py

@@ -1113,7 +1113,8 @@ class PipelineManager(object):
             log.debug("Project %s not in pipeline %s for change %s",
                       item.change.project, self.pipeline, item.change)
             project_in_pipeline = False
-            actions = []
+            actions = self.pipeline.no_jobs_actions
+            item.setReportedResult('NO_JOBS')
         elif item.getConfigErrors():
             log.debug("Invalid config for change %s", item.change)
             # TODOv3(jeblair): consider a new reporter action for this
@@ -1128,7 +1129,8 @@ class PipelineManager(object):
         elif not item.getJobs():
             # We don't send empty reports with +1
             log.debug("No jobs for change %s", item.change)
-            actions = []
+            actions = self.pipeline.no_jobs_actions
+            item.setReportedResult('NO_JOBS')
         elif item.didAllJobsSucceed():
             log.debug("success %s", self.pipeline.success_actions)
             actions = self.pipeline.success_actions

zuul/model.py

@@ -273,6 +273,7 @@ class Pipeline(object):
         self.success_actions = []
         self.failure_actions = []
         self.merge_failure_actions = []
+        self.no_jobs_actions = []
         self.disabled_actions = []
         self.disable_at = None
         self._consecutive_failures = 0
@@ -292,6 +293,7 @@ class Pipeline(object):
             self.success_actions +
             self.failure_actions +
             self.merge_failure_actions +
+            self.no_jobs_actions +
             self.disabled_actions
         )
 

zuul/reporter/__init__.py

@@ -104,6 +104,7 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
             'success': self._formatItemReportSuccess,
             'failure': self._formatItemReportFailure,
             'merge-failure': self._formatItemReportMergeFailure,
+            'no-jobs': self._formatItemReportNoJobs,
             'disabled': self._formatItemReportDisabled
         }
         return format_methods[self._action]
@@ -170,6 +171,17 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
     def _formatItemReportMergeFailure(self, item, with_jobs=True):
         return item.pipeline.merge_failure_message
 
+    def _formatItemReportNoJobs(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.no_jobs_message.format(
+            pipeline=item.pipeline.getSafeAttributes(),
+            change=item.change.getSafeAttributes(),
+            status_url=status_url)
+
     def _formatItemReportDisabled(self, item, with_jobs=True):
         if item.current_build_set.result == 'SUCCESS':
             return self._formatItemReportSuccess(item)