From c49fab69e5001ba33ed059b5c8951d2171f26fda Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 21 Jul 2020 12:07:35 -0700 Subject: [PATCH] enhancements/update/available-update-metadata: 'url' docstring context Fixups to 2eb16cf80d (enhancements/update/available-update-metadata: Propose a new enhancement, 2019-11-19, #123): * Including two sentences from Clayton about how the CVO sources this information and how we build CI/nightly images [1,2]. I think these two sentences are poking holes in the abstraction that the CVO is committing to with the new API, and that consumers should not have to know or care about these implementation details. Clayton feels like they provide useful context about how the system works, and that we'll adjust them as necessary if we ever have cause to alter the implementation. * Downcasing in the Go comments, to match the JSON property, following the Kubernetes API pattern. * 'despire' -> 'despite' typo fix. [1]: https://github.com/openshift/api/pull/521#discussion_r458245881 [2]: https://github.com/openshift/api/pull/521#discussion_r458314229 --- .../update/available-update-metadata.md | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/enhancements/update/available-update-metadata.md b/enhancements/update/available-update-metadata.md index fbdeadebd93..02a9bec7dbe 100644 --- a/enhancements/update/available-update-metadata.md +++ b/enhancements/update/available-update-metadata.md @@ -7,9 +7,11 @@ reviewers: - "@LalatenduMohanty" - "@smarterclayton" approvers: - - TBD + - "@LalatenduMohanty" + - "@sdodson" + - "@smarterclayton" creation-date: 2019-11-19 -last-updated: 2020-07-20 +last-updated: 2020-07-21 status: implementable --- @@ -71,15 +73,15 @@ type Release struct { // +required Image string `json:"image"` - // URL describes the contents of this release and will include - // references to other resources as necessary. Go here if you know - // of no more-specific resource addressing your question for this - // release image. For example, this could link errata or other - // release notes describing the release image. + // url contains information about this release. This URL is set by + // the 'url' metadata property on a release or the metadata returned by + // the update API and should be displayed as a link in user + // interfaces. The URL field may not be set for test or nightly + // releases. // +optional URL URL `json:"url,omitempty"` - // Channels is the set of Cincinnati channels to which the release + // channels is the set of Cincinnati channels to which the release // currently belongs. // +optional Channels []string `json:"channels,omitempty"` @@ -194,9 +196,10 @@ Components like the web console could bypass ClusterVersion and talk to the upst I prefer `homepage`, but [in this thread][homepage-vs-url], Clayton and Lala pushed back against it. The pushback seems to revolve around a belief that domains, organizations, projects and such can have homepages, but that releases are too specific to deserve that name. I think the homepage semantics can apply clearly to any noun, including releases as well as domains, organizations, etc. -But I am comfortable with `url` as long as the declared semantics are "the most generic URI still scoped to this release", and that's what we have here via the "if you know of no more-specific resource" wording. +I am comfortable with `url` as long as the declared semantics are "the most generic URI still scoped to this release, `url` is an appropriate reference for all information about the release". +I have been unable to get Clayton to agree to wording expressing these semantics so far (more discussion [here][url-docs-a] and [here][url-docs-b]), but the existing wording does not rule out those semantics, so maybe we can update the docs later to clarify this point without it being an API-breaking change. -And then `url` instead of `uri` because Kubernetes APIs have lots of URL precedent, despire RFC 3986's URIs making [the location vs. identifier distinction][rfc-3986-s1.1.3] in 2005. +And then `url` instead of `uri` because Kubernetes APIs have lots of URL precedent, despite RFC 3986's URIs making [the location vs. identifier distinction][rfc-3986-s1.1.3] in 2005. ### Pass-through metadata maps @@ -282,3 +285,5 @@ Leave the current `ClusterVersionStatus` alone and just continue to fill the now [rfc-3986-s1.1.3]: https://tools.ietf.org/html/rfc3986#section-1.1.3 [upstream-metadata-suggestion]: https://github.com/openshift/enhancements/pull/123#discussion_r436848838 [upstream-trust]: https://github.com/openshift/enhancements/pull/123#discussion_r349853363 +[url-docs-a]: https://github.com/openshift/enhancements/pull/408#discussion_r458743166 +[url-docs-b]: https://github.com/openshift/enhancements/pull/408#discussion_r460192651