initial working viz of ignored v0 edges #1744

grokspawn · 2025-08-15T17:09:44Z

Description of the change:

This is a first pass in making OLMv0 upgrade graph mechanics visible in rendered graphs, adding to existing olm.deprecations indication rendering.

Bundle versions which are skipped in a graph are outlined in red and have all their contributory edges changed to red, dashed arrows to indicate that they are ignored when calculating upgrades, for e.g.

in this graph, cert-manager-operator.v1.15.1 is skipped, so any graph updates by this version are similarly ignored. This means that users cannot upgrade from v1.15.0 to v1.15.1.

These features are controlled by a new draw-v0-semantics flag (defaults off).
By default, render-graph displays simple upgrade graph mechanics, which aligns to OLMv1 functionality.

Motivation for the change:

Answering user questions recently, it became apparent that OLMv0 interpretation of an upgrade graph includes some interpretation mechanics which aren't well-communicated. These mechanics can result in some user stranding on operator versions because of ignored graph contributions.

Reviewer Checklist

Implementation matches the proposed design, or proposal is updated to match implementation
Sufficient unit test coverage
Sufficient end-to-end test coverage
Docs updated or added to /docs
Commit messages sensible and descriptive

Signed-off-by: grokspawn <[email protected]>

openshift-ci · 2025-08-15T17:09:48Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

codecov · 2025-08-18T17:41:39Z

Codecov Report

❌ Patch coverage is 78.26087% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.24%. Comparing base (3212635) to head (f1c21be).
⚠️ Report is 22 commits behind head on master.

Files with missing lines	Patch %	Lines
alpha/declcfg/write.go	78.26%	17 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1744      +/-   ##
==========================================
+ Coverage   55.17%   55.24%   +0.06%     
==========================================
  Files         136      136              
  Lines       15918    15971      +53     
==========================================
+ Hits         8783     8823      +40     
- Misses       5982     5993      +11     
- Partials     1153     1155       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

camilamacedo86 · 2025-08-19T19:47:00Z

alpha/declcfg/write.go

-			pkgBuilder.WriteString(fmt.Sprintf("    %%%% channel %q\n", filteredChannel.Name))
-			pkgBuilder.WriteString(fmt.Sprintf("    subgraph %s[%q]\n", channelID, filteredChannel.Name))
+			fmt.Fprintf(pkgBuilder, "    %%%% channel %q\n", filteredChannel.Name)
+			fmt.Fprintf(pkgBuilder, "    subgraph %s[%q]\n", channelID, filteredChannel.Name)


bentito · 2025-08-19T20:30:16Z

~~When I run this, even if I try to send 2 to /dev/null, I can't get the warnings out of my way to send the graph output to, for instance, mermaid:~~

bin/opm alpha render-graph quay.io/operatorhubio/catalog:latest|head 2>/dev/null

edit: the above command is wrong, stderr is correctly used, but maybe we should give an example in comments of redirecting as needed:

bin/opm alpha render-graph quay.io/operatorhubio/catalog:latest 2>/dev/null |

grokspawn · 2025-08-19T21:21:26Z

@bentito I think trying to graph an entire catalog will not function properly (though I'd love to see the warnings readout). You would want to limit to a single package, and possibly a lower version range via flags.

I generated customized FBC here, based on a semver catalog template expansion. (Original report here )
I have all the artifacts along the way at https://gist.github.com/grokspawn/e822d025f6718428f08efc2bd02a0d9d

The only missing detail is that, since OPM handles FBC as a hierarchical filesystem, I had to drop the FBC into a directory to manipulate it.

For e.g.:

mkdir /tmp/c4
./bin/opm alpha render-template semver reproducer-semver.yaml > /tmp/c4/catalog.json

./bin/opm alpha render-graph /tmp/c4

bentito · 2025-08-20T14:09:52Z

lgtm

grokspawn · 2025-08-20T17:41:19Z

/approve

openshift-ci · 2025-08-20T17:41:25Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: grokspawn

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~~ [grokspawn]

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

camilamacedo86 · 2025-08-20T17:47:49Z

cmd/opm/alpha/render-graph/cmd.go

 	}
 	cmd.Flags().StringVar(&minEdge, "minimum-edge", "", "the channel edge to be used as the lower bound of the set of edges composing the upgrade graph; default is to include all edges")
 	cmd.Flags().StringVarP(&specifiedPackageName, "package-name", "p", "", "a specific package name to filter output; default is to include all packages in reference")
+	cmd.Flags().BoolVar(&includeV0Semantics, "include-v0-semantics", false, "whether to indicate OLMv0 semantics in the output; default is to simply represent the upgrade graph")


My only concern is with the flag name and description
Could we try to clarify better
If I am adding the flag than I am including that already right?
What does it acctually means v0-semantics?
Maybe:

Suggested change

cmd.Flags().BoolVar(&includeV0Semantics, "include-v0-semantics", false, "whether to indicate OLMv0 semantics in the output; default is to simply represent the upgrade graph")

cmd.Flags().BoolVar(&includeV0Semantics, "--olmv0-semantics", false, "apply OLM v0 upgrade-graph semantics; mark skipped bundles and ignore edges from them when computing paths.")

This PR is the first pass of what I expect will be additional efforts to make how v0 uses upgrade graphs more transparent. I deliberately left the flag very general as a result. This is all in an alpha command chain, so we have a lot of freedom to change the flags in the future as the support improves.

camilamacedo86 · 2025-08-20T17:54:38Z

cmd/opm/alpha/render-graph/cmd.go

 		render               action.Render
 		minEdge              string
 		specifiedPackageName string
+		includeV0Semantics   bool


What about we add a doc here to explain why it is required?
What does it means?
Maybe:

Suggested change

includeV0Semantics bool

// includeV0Semantics show and compute the upgrade graph the way OLM v0 behaves: if a bundle is

// marked as skipped (via skips or skipRange), ignore any upgrade edges coming from that bundle.

// This can reveal why some versions get “stuck.”

includeV0Semantics bool

joelanford · 2025-08-20T20:14:13Z

cmd/opm/alpha/render-graph/cmd.go

 	}
 	cmd.Flags().StringVar(&minEdge, "minimum-edge", "", "the channel edge to be used as the lower bound of the set of edges composing the upgrade graph; default is to include all edges")
 	cmd.Flags().StringVarP(&specifiedPackageName, "package-name", "p", "", "a specific package name to filter output; default is to include all packages in reference")
+	cmd.Flags().BoolVar(&includeV0Semantics, "include-v0-semantics", false, "whether to indicate OLMv0 semantics in the output; default is to simply represent the upgrade graph")


My nit is s/include/use/ for the name of the flag/variable, etc.

"Include" implies multiple $things could be included, all contributing. Whereas "use" has more of a mutual exclusive feel, which I think is more of what we're going for? I also notice that the actual mermaid renderer uses "use" terminology, so this would have better overall alignment as well.

I’d prefer to use that as well.
Sorry for being so nitpicky, but could you please include “ring a bell”?

I updated to make the flag naming consistent across the front- & back-ends.

I don't understand the "ring a bell" reference.

Signed-off-by: grokspawn <[email protected]>

camilamacedo86 · 2025-08-21T17:05:15Z

/lgtm

initial working viz of ignored v0 edges

6f87b9b

Signed-off-by: grokspawn <[email protected]>

openshift-ci bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 15, 2025

grokspawn force-pushed the v0-graph-mechanics branch from 1d01c9b to 9f8c791 Compare August 18, 2025 16:29

grokspawn marked this pull request as ready for review August 18, 2025 16:29

openshift-ci bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 18, 2025

openshift-ci bot requested review from anik120 and kevinrizza August 18, 2025 16:30

grokspawn force-pushed the v0-graph-mechanics branch 2 times, most recently from 0e8cfc1 to 7d3cf25 Compare August 18, 2025 17:37

This was referenced Aug 19, 2025

eliminate skipping same-Y.maxZ, which should only replace #1749

Merged

validate fail for stranded channel entries #1750

Merged

camilamacedo86 reviewed Aug 19, 2025

View reviewed changes

openshift-ci bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 20, 2025

camilamacedo86 reviewed Aug 20, 2025

View reviewed changes

joelanford reviewed Aug 20, 2025

View reviewed changes

initial semantic refactoring

b35b44c

grokspawn force-pushed the v0-graph-mechanics branch from 7d3cf25 to b35b44c Compare August 21, 2025 13:34

lint updates

f1c21be

Signed-off-by: grokspawn <[email protected]>

grokspawn force-pushed the v0-graph-mechanics branch from 371dd97 to f1c21be Compare August 21, 2025 15:57

openshift-ci bot assigned camilamacedo86 Aug 21, 2025

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Aug 21, 2025

openshift-merge-bot bot merged commit 2629279 into operator-framework:master Aug 21, 2025
13 checks passed

chiragkyal mentioned this pull request Aug 25, 2025

OCPBUGS-60289: Fix upgrade path for v1.15.0->v1.15.1->v1.16.1 openshift/cert-manager-operator-release#489

Merged

grokspawn deleted the v0-graph-mechanics branch August 27, 2025 18:57

github-actions bot mentioned this pull request Aug 30, 2025

[operator-framework/operator-registry] v1.57.0 vdemeester/chapeau-rouge#262

Open

	cmd.Flags().BoolVar(&includeV0Semantics, "include-v0-semantics", false, "whether to indicate OLMv0 semantics in the output; default is to simply represent the upgrade graph")
	cmd.Flags().BoolVar(&includeV0Semantics, "--olmv0-semantics", false, "apply OLM v0 upgrade-graph semantics; mark skipped bundles and ignore edges from them when computing paths.")

-		includeV0Semantics   bool
+		// includeV0Semantics show and compute the upgrade graph the way OLM v0 behaves: if a bundle is
+		// marked as skipped (via skips or skipRange), ignore any upgrade edges coming from that bundle.
+		// This can reveal why some versions get “stuck.”
+		includeV0Semantics   bool

initial working viz of ignored v0 edges #1744

initial working viz of ignored v0 edges #1744

Uh oh!

Conversation

grokspawn commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci bot commented Aug 15, 2025

Uh oh!

codecov bot commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

camilamacedo86 Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

bentito commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grokspawn commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bentito commented Aug 20, 2025

Uh oh!

grokspawn commented Aug 20, 2025

Uh oh!

openshift-ci bot commented Aug 20, 2025

Uh oh!

camilamacedo86 Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grokspawn Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joelanford Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

grokspawn Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 commented Aug 21, 2025

Uh oh!

Uh oh!

Uh oh!

grokspawn commented Aug 15, 2025 •

edited

Loading

codecov bot commented Aug 18, 2025 •

edited

Loading

bentito commented Aug 19, 2025 •

edited

Loading

grokspawn commented Aug 19, 2025 •

edited

Loading

camilamacedo86 Aug 20, 2025 •

edited

Loading

camilamacedo86 Aug 20, 2025 •

edited

Loading