From 0a7e102f0d66962082a8164728dae168f493548c Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Tue, 11 Aug 2026 07:30:44 +0000 Subject: [PATCH] Add docs for opting out of release-5.0 to release-4.23 fast-forwarding Document how optional operator teams can opt out of automated fast-forwarding from release-5.0 to release-4.23 by adding their repository to the repo-brancher-controller ignore list. Covers the timeline around the August 14, 2026 branch cut, ignore list matching semantics, and responsibilities after opting out. Tracking: DPTP-4980 Co-Authored-By: Claude Opus 4.6 --- .../how-tos/opting-out-of-fast-forwarding.md | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 content/en/how-tos/opting-out-of-fast-forwarding.md diff --git a/content/en/how-tos/opting-out-of-fast-forwarding.md b/content/en/how-tos/opting-out-of-fast-forwarding.md new file mode 100644 index 00000000..daaf790d --- /dev/null +++ b/content/en/how-tos/opting-out-of-fast-forwarding.md @@ -0,0 +1,139 @@ +--- +title: "Opting Out of Fast-Forwarding from release-5.0 to release-4.23" +description: How optional operator teams can opt out of automated fast-forwarding from release-5.0 to release-4.23 and maintain the release-4.23 branch independently. +--- + +This document describes how optional operator teams can opt out of the automated fast-forwarding +that keeps `release-4.23` in sync with `release-5.0`. After opting out, your team is responsible +for maintaining the `release-4.23` branch directly. + +## Background + +The `repo-brancher-controller` (source in [openshift/ci-tools](https://github.com/openshift/ci-tools/tree/main/cmd/repo-brancher-controller/)) +automatically fast-forwards content between release branches. Under the current configuration, +`release-5.0` is forwarded to `release-4.23` so that both branches stay in sync without manual +intervention. Direct merges to fast-forwarded branches are blocked by CI. + +Some optional operator teams need to ship different content on the `release-4.23` branch than what +lands on `release-5.0`. For these teams, the forwarding can be disabled by adding the repository +to the controller's ignore list. + +{{< alert title="Important" color="warning" >}} +Opting out is **all-or-nothing**. There is no partial forwarding mode — once you opt out, +no content from `release-5.0` is forwarded to `release-4.23` for your repository. Your team +becomes solely responsible for maintaining the `release-4.23` branch, including backporting +any fixes that should appear in both branches. +{{< /alert >}} + +## Timeline + +The branch cut is scheduled for **August 14, 2026**. The behavior differs before and after the cut: + +### Before branch cut + +| Branch | Forwards to | Direct merges | +|-|-|-| +| `main` | `release-5.0` and `release-4.23` | blocked on release branches | +| `release-5.0` | `release-4.23` | blocked | + +### After branch cut + +| Branch | Behavior | +|-|-| +| `main` | opens for 5.1 development | +| `release-5.0` | detaches from `main`; accepts direct merges | +| `release-4.23` (opted-out repos) | accepts direct merges; your team maintains it | +| `release-4.23` (default repos) | still fast-forwarded from `release-5.0` | + +## How to opt out + +### 1. Locate the forwarding configuration + +The forwarding configuration lives in the +[openshift/release](https://github.com/openshift/release) repository at: + +{{< highlight text >}} +clusters/app.ci/repo-brancher-controller/repo-brancher-controller.yaml +{{< / highlight >}} + +Inside that file, a `ConfigMap` contains the controller's `config.yaml`. The section you need to +modify is `release_branches`, which controls forwarding between release branches. + +### 2. Add your repository to the ignore list + +Find the `release_branches` section and add your org/repo to the `ignore` list under the +appropriate `forward` block. For most optional operators, this is the `family: release` block +with `source: "5.0"` and `target: "4.23"`: + +{{< highlight yaml >}} +release_branches: + - source: "5.0" + forward: + - family: release + targets: + - "4.23" + ignore: + - org: Azure + repo: ARO-HCP + - org: openshift-eng + # Add your repository here: + - org: your-github-org + repo: your-repo-name +{{< / highlight >}} + +### 3. Submit a pull request + +Submit a pull request to [openshift/release](https://github.com/openshift/release) with this +change. Once the PR merges, the configuration is **hot-reloaded** — no controller restart is +needed. Forwarding for your repository will stop on the next cycle. + +## Ignore list matching + +Each entry in the `ignore` list can match on any combination of the following fields: + +| Field | Effect | +|-|-| +| `org` | Matches all repositories in the given GitHub organization | +| `repo` | Matches a specific repository (must be combined with `org`) | +| `source` | Matches forwarding from a specific source branch version | +| `target` | Matches forwarding to a specific target branch version | + +For example, to ignore an entire organization: + +{{< highlight yaml >}} +ignore: + - org: my-org +{{< / highlight >}} + +To ignore a single repository: + +{{< highlight yaml >}} +ignore: + - org: openshift + repo: my-operator +{{< / highlight >}} + +When both an `only` (allowlist) and an `ignore` (blocklist) entry match a repository, +**`ignore` wins** and the repository is excluded from forwarding. + +## What happens after opting out + +Once your repository is on the ignore list and the change has merged: + +1. The `repo-brancher-controller` stops fast-forwarding `release-5.0` to `release-4.23` for + your repository. +2. CI no longer blocks direct merges to `release-4.23` on your repository (after branch cut). +3. Your team is responsible for cherry-picking or merging any changes that should appear on + `release-4.23`. + +{{< alert title="Warning" color="warning" >}} +Once you opt out, there is no automated mechanism to keep `release-4.23` up to date with +`release-5.0`. If a critical fix lands on `release-5.0`, your team must manually apply it +to `release-4.23`. +{{< /alert >}} + +## Tracking + +This process is tracked under [DPTP-4980](https://issues.redhat.com/browse/DPTP-4980). If you +have questions or run into issues, reach out on the `#forum-ocp-crt` Slack channel or comment +on the tracking issue.