From d04bd778dfa45212eeeecabaee9447223144c381 Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Fri, 15 Mar 2024 08:58:07 -0700 Subject: [PATCH] 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 | 53 ++++++++++++++++++- .../notes/item-url-3b9b6a2c5eb4315b.yaml | 7 +++ zuul/driver/gerrit/gerritconnection.py | 4 +- zuul/driver/github/githubreporter.py | 4 +- zuul/model.py | 2 +- zuul/reporter/__init__.py | 18 ++++--- 6 files changed, 75 insertions(+), 13 deletions(-) create mode 100644 releasenotes/notes/item-url-3b9b6a2c5eb4315b.yaml diff --git a/doc/source/config/pipeline.rst b/doc/source/config/pipeline.rst index d877014dea..107feec795 100644 --- a/doc/source/config/pipeline.rst +++ b/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. diff --git a/releasenotes/notes/item-url-3b9b6a2c5eb4315b.yaml b/releasenotes/notes/item-url-3b9b6a2c5eb4315b.yaml new file mode 100644 index 0000000000..c8dc5e108b --- /dev/null +++ b/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. diff --git a/zuul/driver/gerrit/gerritconnection.py b/zuul/driver/gerrit/gerritconnection.py index 5c120c9feb..95e7a51af1 100644 --- a/zuul/driver/gerrit/gerritconnection.py +++ b/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: diff --git a/zuul/driver/github/githubreporter.py b/zuul/driver/github/githubreporter.py index c77c4aea01..ccab2c4fa9 100644 --- a/zuul/driver/github/githubreporter.py +++ b/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) diff --git a/zuul/model.py b/zuul/model.py index 11e61edff9..04e546f7ce 100644 --- a/zuul/model.py +++ b/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 diff --git a/zuul/reporter/__init__.py b/zuul/reporter/__init__.py index fa0dc81127..9241ea0ed5 100644 --- a/zuul/reporter/__init__.py +++ b/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):