enhancements/update/available-update-metadata: 'url' docstring context #408

wking · 2020-07-21T19:23:23Z

Fixups to 2eb16cf (#123):

Including two sentences from @smarterclayton about how the CVO sources this information and how we build CI/nightly images.
Downcasing in the Go comments, to match the JSON property, following the Kubernetes API pattern.
"despire" -> "despite" typo fix.

wking · 2020-07-21T19:40:19Z

I've pushed 91c60e8 -> a46ca76 removing the:

This URL is set by the url metadata property on a release...

sentence, because it conflicts with the enhancement proposal's:

Then, in the cluster-version operator (CVO), this enhancement proposes porting existing logic like available-update translation and available-update lookup to preserve the Cincinnati metadata, with information from the release image itself taking precedence over information from Cincinnati.

implementation.

wking · 2020-07-21T19:45:42Z

I've pushed a46ca76 -> b22d4e6 adding this updated sentence about the url source and linking suggestion.

LalatenduMohanty · 2020-07-22T12:07:50Z

enhancements/update/available-update-metadata.md

  // 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.
+  // release image. This URL is set by the 'url' metadata property on


Go here if you know of no more-specific resource addressing your question for this of no more-specific resource addressing your question for this makes the meaning of the comment odd and confusing. Why do we need to say this here? It does not seem like a necessary sentence because the sentences before it and after it communicates things in a better way.

As described here, my resistance to url, and preference for homepage, revolved around url being generic, with no clear semantic meaning. Clayton's argument was that the semantics are that this property references the most-generic resource scoped to this release, i.e. that it is a good choice regardless of which released-scoped information you are seeking. I want some sort of most-generic statement like my "no more-specific resource" line to get this across. For example, if you sometimes know of another release-scoped resource (e.g., an entry for this release in a changelog or release notes), falling back to the more-generic url when you cannot determine your specific link would be perfectly acceptable, and not a hack.

@wking Do you have a concrete example of where this might link to? For instance, for 4.5.2, where would url take you?

For example, if you sometimes know of another release-scoped resource (e.g., an entry for this release in a changelog or release notes), falling back to the more-generic url when you cannot determine your specific link would be perfectly acceptable, and not a hack.

The language is vague enough in the API doc that it's not clear to me when to use something other than url. Console always links to the release notes today. Would that sometimes be better?

If the concern is that the link won't have detailed release notes, is it enough simply to say that?

Do you have a concrete example of where this might link to?

The most-generic semantics mean that you shouldn't need a concrete example. Whatever they link to should be generic enough for any release-scoped use case. But practically, these will continue to link the errata pages for OCP releases, and release-controller detail pages or some such for FCOS releases.

The language is vague enough in the API doc that it's not clear to me when to use something other than url.

We want the language to clearly communicate:

If you know of a specific link for your purpose, by all means, use that.

Regardless of whether you know of a specific link for your release-scoped purpose, using the url value is fine. It is the most-generic release-scoped link there is, so it will never be wrong. The worst it can be is "not as specific as $ALTERNATIVE".

Console always links to the release notes today. Would that sometimes be better?

So yes, ignoring this value and linking to the release notes (when you know where they'll be) is fine. And you should fall back to this value for the "release notes link" use-case when you are not sure of a more-specific release notes target. We want the API docs to make that clear without folks having to ask for clarification out of band. Can you float some alternative wording if the current proposal here does not express this clearly?

If the concern is that the link won't have detailed release notes, is it enough simply to say that?

If detailed release notes exist, the url value should either link to them or a more-generic page that in turn links to the release notes (OCP errata link to release notes today). If detailed release notes exist and the url value links to a page from which the release notes are not discoverable, that would be a bug we could file against either ART (who are deciding to link the errata page with url) or the Errata folks (who are deciding what content to put on the errata page).

IMO, it's more helpful to give examples of what the page is...

I'm ok with giving examples. But I think we're doing it wrong if the only way we can describe the intended values is by saying "it's going to be content like $existing_examples". We should be able to describe the content in a way that stands alone, and then supplement that normative definition with informative examples.

I don't know that you need to give clients permission to use another link. People will do that anyway if they want :) And I wouldn't assume the link is ever "wrong."

If we had URI properties for license and releaseNotes, using the value of releaseNotes and saying "license is here" when license was unset would be clearly wrong. The special thing about the most-generic url is that saying "license is here" and linking the the value of url would be perfectly fine, because you could assume that the license information would be easily discoverable from the generic url target.

Restored:

For example, this could link errata or other release notes describing the release image.

with b22d4e6 -> 73a1139, to address @spadgett's "Do you have a concrete example of where this might link to?".

I don't like this language. Errata is confusing to non OCP customers, release notes is confusing to OCP customers. This sentence is not a good sentence for those reasons.

The URL will contain information about the release.

is the minimum bar. I am fine with leaving OCP or OKD language out right now.

I am fine with leaving OCP or OKD language out right now.

Ok, back to b22d4e6.

The URL will contain information about the release.

Pushed b22d4e6 -> d859e06, replacing the first sentence with Clayton's new suggestion.

spadgett

/lgtm
/hold
for other feedback

spadgett

/lgtm

smarterclayton · 2020-07-24T17:32:11Z

enhancements/update/available-update-metadata.md

@@ -71,15 +74,16 @@ 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
+  // url contains information about the release. Go here if you know


Remove the Go here if you know of no more-specific resource. It is not useful.

Remove the Go here if you know of no more-specific resource.

Dropped in d859e06 -> c49fab6 with notes in the homepage vs url section complaining about you forcing me to do this ;)

And updated the Cincinnati-graph property definition to match the new first sentence with c49fab6 -> 12eff48.

Fixups to 2eb16cf (enhancements/update/available-update-metadata: Propose a new enhancement, 2019-11-19, openshift#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]: openshift/api#521 (comment) [2]: openshift/api#521 (comment)

sdodson · 2020-07-24T19:22:32Z

/lgtm
Dissent noted, thanks for your flexibility. I believe this addresses the concerns raised.

smarterclayton · 2020-07-24T20:08:54Z

/approve
/hold cancel

openshift-ci-robot · 2020-07-24T20:09:12Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sdodson, smarterclayton, spadgett, wking

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [sdodson,smarterclayton,spadgett]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

This commit adds the ability to store release metadata, implementing openshift/enhancements@2eb16cf80d (enhancements/update/available-update-metadata: Propose a new enhancement, 2020-07-20, openshift/enhancements#123) as adjusted by openshift/enhancements@12eff48079 (enhancements/update/available-update-metadata: 'url' docstring context, 2020-07-21, openshift/enhancements#408). For example the list of channels that a release is in: $ curl -sH 'Accept:application/json' 'https://api.openshift.com/api/upgrades_info/v1/graph?channel=stable-4.2' | jq -r '.nodes[] | select(.version == "4.2.4").metadata["io.openshift.upgrades.graph.release.channels"] | split(",")[]' candidate-4.2 fast-4.2 stable-4.2 That will allow the console and other downstream tooling to expose a list of channels available to a given cluster right now, instead of hard-coding an expected list [1]. This will account for things like phased releases, where we may not recommend an upgrade for your particular stable-4.2 cluster even though we are recommending the upgrade for other stable-4.2 clusters. Pivoting around this retyping in Go will require consumer bumps, but I don't think it's a breaking change because the only YAML removal is 'force', which is meaningless in AvailableUpdates. So I don't think this needs to count as a backwards-compat-breaking schema bump. Autogenerated bumps via: $ unset GOBIN # vendor/k8s.io/code-generator/generate-groups.sh and such require "${GOPATH}/bin/deepcopy-gen" $ go get k8s.io/gengo/examples/deepcopy-gen $ hack/update-deepcopy.sh $ hack/update-swagger-docs.sh $ make update-codegen-crds [1]: openshift/console#2935

openshift-ci-robot requested review from dustymabe and eparis July 21, 2020 19:23

wking force-pushed the release-url-rewording branch 2 times, most recently from 91c60e8 to a46ca76 Compare July 21, 2020 19:38

wking force-pushed the release-url-rewording branch from a46ca76 to b22d4e6 Compare July 21, 2020 19:44

wking mentioned this pull request Jul 21, 2020

config/v1: New Release type for ClusterVersionStatus openshift/api#521

Merged

LalatenduMohanty suggested changes Jul 22, 2020

View reviewed changes

wking force-pushed the release-url-rewording branch from b22d4e6 to 73a1139 Compare July 24, 2020 17:04

spadgett approved these changes Jul 24, 2020

View reviewed changes

openshift-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jul 24, 2020

openshift-ci-robot assigned spadgett Jul 24, 2020

openshift-ci-robot added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Jul 24, 2020

wking force-pushed the release-url-rewording branch from 73a1139 to b22d4e6 Compare July 24, 2020 17:14

openshift-ci-robot removed the lgtm Indicates that a PR is ready to be merged. label Jul 24, 2020

spadgett approved these changes Jul 24, 2020

View reviewed changes

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Jul 24, 2020

wking force-pushed the release-url-rewording branch from b22d4e6 to d859e06 Compare July 24, 2020 17:25

openshift-ci-robot removed the lgtm Indicates that a PR is ready to be merged. label Jul 24, 2020

smarterclayton reviewed Jul 24, 2020

View reviewed changes

wking force-pushed the release-url-rewording branch from d859e06 to c49fab6 Compare July 24, 2020 19:08

wking force-pushed the release-url-rewording branch from c49fab6 to 12eff48 Compare July 24, 2020 19:18

openshift-ci-robot assigned sdodson Jul 24, 2020

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Jul 24, 2020

openshift-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jul 24, 2020

openshift-merge-robot merged commit ebf0cd3 into openshift:master Jul 24, 2020

wking deleted the release-url-rewording branch July 24, 2020 20:36

wking mentioned this pull request Nov 9, 2020

enhancements/update/channel-metadata: Distribute channel description strings #531

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

enhancements/update/available-update-metadata: 'url' docstring context #408

enhancements/update/available-update-metadata: 'url' docstring context #408

wking commented Jul 21, 2020

wking commented Jul 21, 2020

wking commented Jul 21, 2020

LalatenduMohanty Jul 22, 2020

wking Jul 22, 2020

spadgett Jul 23, 2020

spadgett Jul 23, 2020

wking Jul 23, 2020

wking Jul 24, 2020

wking Jul 24, 2020

smarterclayton Jul 24, 2020

wking Jul 24, 2020

wking Jul 24, 2020

spadgett left a comment

spadgett left a comment

smarterclayton Jul 24, 2020

wking Jul 24, 2020

wking Jul 24, 2020

sdodson commented Jul 24, 2020

smarterclayton commented Jul 24, 2020

openshift-ci-robot commented Jul 24, 2020

enhancements/update/available-update-metadata: 'url' docstring context #408

enhancements/update/available-update-metadata: 'url' docstring context #408

Conversation

wking commented Jul 21, 2020

wking commented Jul 21, 2020

wking commented Jul 21, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spadgett left a comment

Choose a reason for hiding this comment

spadgett left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdodson commented Jul 24, 2020

smarterclayton commented Jul 24, 2020

openshift-ci-robot commented Jul 24, 2020