Merge "Replace status_url with item_url in pipeline reporter templates"

doc/source/config/pipeline.rst

@@ -205,13 +205,45 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       :default: Starting {pipeline.name} jobs.
 
       The introductory text in reports when jobs are started.
-      Three replacement fields are available ``status_url``, ``pipeline`` and
-      ``change``.
+      The following replacement fields are available:
+
+      pipeline
+        The name of the pipeline
+      item_url
+        The full URL to information about the item in the web UI
+      change
+        Deprecated: information about the change
+      changes
+        Deprecated: information about the change
+      status_url
+        Deprecated: the configured web ui status page root
+
+      .. warning:: The replacement fields ``change``, ``changes``, and
+                   ``status_url`` are deprecated.  Use ``item_url``,
+                   which is automatically the best URL for information
+                   about the item instead.
 
    .. attr:: enqueue-message
 
       The introductory text in reports when an item is enqueued.
       Empty by default.
+      The following replacement fields are available:
+
+      pipeline
+        The name of the pipeline
+      item_url
+        The full URL to information about the item in the web UI
+      change
+        Deprecated: information about the change
+      changes
+        Deprecated: information about the change
+      status_url
+        Deprecated: the configured web ui status page root
+
+      .. warning:: The replacement fields ``change``, ``changes``, and
+                   ``status_url`` are deprecated.  Use ``item_url``,
+                   which is automatically the best URL for information
+                   about the item instead.
 
    .. attr:: merge-conflict-message
       :default: Merge failed.
@@ -224,6 +256,23 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
 
       The introductory text in reports when an item is dequeued
       without running any jobs.  Empty by default.
+      The following replacement fields are available:
+
+      pipeline
+        The name of the pipeline
+      item_url
+        The full URL to information about the item in the web UI
+      change
+        Deprecated: information about the change
+      changes
+        Deprecated: information about the change
+      status_url
+        Deprecated: the configured web ui status page root
+
+      .. warning:: The replacement fields ``change``, ``changes``, and
+                   ``status_url`` are deprecated.  Use ``item_url``,
+                   which is automatically the best URL for information
+                   about the item instead.
 
    .. attr:: dequeue-message
       :default: Build canceled.

releasenotes/notes/item-url-3b9b6a2c5eb4315b.yaml

@@ -0,0 +1,7 @@
+---
+deprecations:
+  - |
+    The replacement fields ``change``, ``changes``, and ``status_url``
+    available in some pipeline reporter configurations are deprecated.
+    Use ``item_url``, which is automatically the best URL for
+    information about the item instead.

zuul/driver/gerrit/gerritconnection.py

@@ -1254,7 +1254,7 @@ class GerritConnection(ZKChangeCacheMixin, ZKBranchCacheMixin, BaseConnection):
             checkinfo['started'] = fmt(item.enqueue_time)
             if item.report_time:
                 checkinfo['finished'] = fmt(item.report_time)
-            url = item.formatStatusUrl()
+            url = item.formatItemUrl()
             if url:
                 checkinfo['url'] = url
         if checkinfo:
@@ -1299,7 +1299,7 @@ class GerritConnection(ZKChangeCacheMixin, ZKBranchCacheMixin, BaseConnection):
                 if file_comments:
                     if self.version >= (2, 15, 0):
                         file_comments = copy.deepcopy(file_comments)
-                        url = item.formatStatusUrl()
+                        url = item.formatItemUrl()
                         for comments in itertools.chain(
                                 file_comments.values()):
                             for comment in comments:

zuul/driver/github/githubreporter.py

@@ -177,7 +177,7 @@ class GithubReporter(BaseReporter):
             sha = change.newrev
         state = self._commit_status
 
-        url = item.formatStatusUrl()
+        url = item.formatItemUrl()
 
         description = '%s status: %s' % (item.pipeline.name,
                                          self._commit_status)
@@ -275,7 +275,7 @@ class GithubReporter(BaseReporter):
             change, self.config, self.context, message
         )
 
-        details_url = item.formatStatusUrl()
+        details_url = item.formatItemUrl()
 
         # Check for inline comments that can be reported via checks API
         file_comments = self.getFileComments(item, change)

zuul/model.py

@@ -5803,7 +5803,7 @@ class QueueItem(zkobject.ZKObject):
                 result = job.failure_message
         return (result, url)
 
-    def formatStatusUrl(self):
+    def formatItemUrl(self):
         # If we don't have a web root set, we can't format any url
         if not self.pipeline.tenant.web_root:
             # Apparently we have no website

zuul/reporter/__init__.py

@@ -176,10 +176,12 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
         if status_url:
             status_url = item.formatUrlPattern(status_url)
 
+        # change, changes, and status_url are deprecated
         return item.pipeline.enqueue_message.format(
             pipeline=item.pipeline.getSafeAttributes(),
             change=item.changes[0].getSafeAttributes(),
             changes=[c.getSafeAttributes() for c in item.changes],
+            item_url=item.formatItemUrl(),
             status_url=status_url)
 
     def _formatItemReportStart(self, item, with_jobs=True):
@@ -187,18 +189,20 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
         if status_url:
             status_url = item.formatUrlPattern(status_url)
 
+        # change, changes, and status_url are deprecated
         return item.pipeline.start_message.format(
             pipeline=item.pipeline.getSafeAttributes(),
             change=item.changes[0].getSafeAttributes(),
             changes=[c.getSafeAttributes() for c in item.changes],
+            item_url=item.formatItemUrl(),
             status_url=status_url)
 
     def _formatItemReportSuccess(self, item, with_jobs=True):
         msg = item.pipeline.success_message
         if with_jobs:
-            status_url = item.formatStatusUrl()
-            if status_url is not None:
-                msg += '\n' + status_url
+            item_url = item.formatItemUrl()
+            if item_url is not None:
+                msg += '\n' + item_url
             msg += '\n\n' + self._formatItemReportJobs(item)
         return msg
 
@@ -228,9 +232,9 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
         else:
             msg = item.pipeline.failure_message
             if with_jobs:
-                status_url = item.formatStatusUrl()
-                if status_url is not None:
-                    msg += '\n' + status_url
+                item_url = item.formatItemUrl()
+                if item_url is not None:
+                    msg += '\n' + item_url
                 msg += '\n\n' + self._formatItemReportJobs(item)
         return msg
 
@@ -253,10 +257,12 @@ class BaseReporter(object, metaclass=abc.ABCMeta):
         if status_url:
             status_url = item.formatUrlPattern(status_url)
 
+        # change, changes, and status_url are deprecated
         return item.pipeline.no_jobs_message.format(
             pipeline=item.pipeline.getSafeAttributes(),
             change=item.changes[0].getSafeAttributes(),
             changes=[c.getSafeAttributes() for c in item.changes],
+            item_url=item.formatItemUrl(),
             status_url=status_url)
 
     def _formatItemReportDisabled(self, item, with_jobs=True):