[perdasilva]

Dependency and merge order

Merge after #3147. This branch is based directly on main (40e1251f), not stacked on the implementation branch. It documents the spec-level progressDeadlineMinutes API introduced by #3147, so merging it first would describe an API that is not yet on main.

Summary

• Add docs/draft/concepts/clusterobjectdeployment.md covering COD responsibilities, revision identity and ownership, status conditions, rollout deadlines and recovery, history retention, and ClusterExtension integration.
• Keep COS concepts focused on resource readiness and completion, and link deployment-level policy to the new COD page.
• Keep the standalone tutorial focused on the walkthrough, linking detailed semantics to the concept page; correct stale object/ref field names and ClusterExtension integration text.
• Update the historical COD design notice to point to current deadline semantics.

These four hand-authored documentation changes were split out of #3147. Generated API references, API/controller changes, tests, and the corrected standalone sample remain in #3147. No runtime code, API definitions, or generated artifacts change in this PR.

Verification

• make verify passes without tracked drift.
• All 20 local Markdown links and anchors in the changed documentation resolve; no references remain to removed sections.
• The YAML example strictly decodes against 🐛: move ClusterObjectDeployment progressDeadlineMinutes to spec level #3147's COD API types, as required by the merge dependency.
• The tutorial JSON patch targets the actual sample's ConfigMap message.
• Baseline shared E2E helper tests pass with race detection.
• Confirmed that combining this PR with the reduced 🐛: move ClusterObjectDeployment progressDeadlineMinutes to spec level #3147 preserves the original combined file tree exactly.

MkDocs rendering and live E2E scenarios were not run. MkDocs is not installed locally.

Summary by CodeRabbit

• Documentation
  • Added an overview of the experimental, cluster-scoped ClusterObjectDeployment (COD) API, covering revisions, status, rollout deadlines, history, deletion, and ClusterExtension integration.
  • Clarified that rollout time is budgeted from the current ClusterObjectSet’s creation, and that changing the deadline recalculates the budget—even after timeout. ClusterObjectSet no longer exposes a deadline field.
  • Updated the management tutorial with revised commands, deadline guidance, and links to concept and status-condition documentation.

[netlify]

👷 Deploy request for olmv1 pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	922c9d9

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

The changes add a COD concept document and update related design, COS concept, and tutorial documentation. They describe COD revisions, rollout conditions and deadlines, history handling, and ClusterExtension integration.

Changes: ClusterObjectDeployment documentation

Layer / File(s)	Summary
COD contract and revisions docs/draft/concepts/clusterobjectdeployment.md, docs/draft/tutorials/manage-clusterobjectdeployments.md	The concept describes COD fields, revision numbering, and which template edits create revisions. The tutorial links to those rules.
Rollout status and lifecycle docs/draft/concepts/clusterobjectdeployment.md, docs/designs/object-controller/clusterobjectdeployment.md, docs/draft/concepts/clusterobjectsets.md, docs/draft/tutorials/manage-clusterobjectdeployments.md	The documents describe ownership checks, status conditions, deadline behavior, and history pruning. The design notice marks its deadline semantics as historical, and the tutorial explains how to change the rollout budget.
Integration and tutorial workflow docs/draft/concepts/clusterobjectdeployment.md, docs/draft/concepts/clusterobjectsets.md, docs/draft/tutorials/manage-clusterobjectdeployments.md	The concept describes ClusterExtension integration. The tutorial updates the manifest patch example, referenced-content guidance, and standalone workflow description. The COS concept adds links to COD documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Possibly related PRs

• operator-framework/operator-controller#3055: Implements the COD revision-level deadline behavior described in this documentation.
• operator-framework/operator-controller#3078: Removes the COS deadline field referenced in the updated contract.
• operator-framework/operator-controller#3147: Moves the deadline field to COD and changes its revision behavior.

Suggested reviewers: grokspawn, fao89, dtfranz

Merge Risk: Minimal · up to 922c9

This PR adds and updates documentation for ClusterObjectDeployment rollout behavior and has no runtime effect. It documents the API from #3147, so it should merge after that PR. No actionable risk remains.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly identifies the main documentation change and uses the required documentation icon.
Description check		The description provides the change summary, motivation, merge dependency, scope, and verification results. It does not reproduce the reviewer checklist or provide an explicit issue link, but the requ…
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description provides the change summary, motivation, merge dependency, scope, and verification results. It does not reproduce the reviewer checklist or provide an explicit issue link, but the required context is mostly complete.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.)

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Enterprise
• Run ID: e9a758fb-3deb-40d8-ae3e-80499c78f714

Commits

Reviewing files that changed from the base of the PR and between 40e1251 and 922c9d9.

Files selected for processing: 4

• docs/designs/object-controller/clusterobjectdeployment.md
• docs/draft/concepts/clusterobjectdeployment.md
• docs/draft/concepts/clusterobjectsets.md
• docs/draft/tutorials/manage-clusterobjectdeployments.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

[tmshort]

/approve

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tmshort

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• docs/OWNERS [tmshort]

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

[fao89]

/lgtm