Replace status_url with item_url in pipeline reporter templates

We have some replacement fields designed to allow users to construct
deep links to the status page, but that is more difficult to do now
that items may have more than one change.  Moreover, users shouldn't
need to do it at all since Zuul already knows how to do that.

Make a new field, "item_url" which is the correct status page url,
and encourage users to use that instead.  Deprecate status_url,
change, and changes which are now difficult to use correctly.

Change-Id: I40e98ed220a13b8d2edddf510bab133b05845751

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

@@ -1244,7 +1244,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:
@@ -1289,7 +1289,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

@@ -5752,7 +5752,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):