Skip to content

Commit 87e3a6d

Browse files
syedrikosyedriko
committed
LCORE-1720: Description of the release process
1 parent 8dbcd06 commit 87e3a6d

1 file changed

Lines changed: 216 additions & 0 deletions

File tree

‎docs/release-organization.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Lightspeed Core Release Organization
2+
3+
This document describes how Konflux **Applications**, **ReleasePlans**, **components**, **ReleasePlanAdmission (RPA)**, the Comet (catalog) container images, and release practice fit together, and how to perform **micro** and **minor** releases.
4+
5+
---
6+
7+
## 1. Goals of the layout
8+
9+
- **Independent release branches**: Each maintained Git release branch (for example `main` for the current minor, `release/0.5` for 0.5.x) can be built and released without blocking the other.
10+
- **Predictable user-facing images**: Comet exposes a fixed set of image repositories and tag conventions so consumers always pull from known Red Hat registry paths.
11+
- **Controlled promotion**: RPA maps Konflux **components** to the **repositories** and **tags** that land on `registry.redhat.io`, so only intended builds are published under `latest`, `x.y-latest`, full versions, and RCs.
12+
13+
---
14+
15+
## 2. Konflux
16+
17+
Konflux groups Lightspeed Core work by **Application** (one per minor release branch), **component** builds inside that application, and **release** wiring: a `**ReleasePlan`** per application in the developer tenant, paired with **ReleasePlanAdmission (RPA)** in the managed tenant so promotions land on the right `registry.redhat.io` paths and tags.
18+
19+
### 2.1 Applications and components
20+
21+
There is **one Konflux application per Lightspeed Core minor release branch** (not one app per patch). Today that pattern is illustrated as:
22+
23+
24+
| Application (example name) | Purpose | Typical Git revisions |
25+
| -------------------------- | -------------------------- | ----------------------------------------------------- |
26+
| `lightspeed-core-0.6` | Current development branch | `lightspeed-stack` and `rag-content` track `**main`** |
27+
| `lightspeed-core-0.5` | Maintained 0.5.x branch | Same repos track `**release/0.5**` |
28+
29+
30+
> **Note:** Some legacy naming misspells the application as `lighspeed-core-*`; the intended name is `**lightspeed-core-*`**.
31+
32+
Each application owns a **set of components** (one or more repositories built for that branch). Example structure:
33+
34+
**Application `lightspeed-core-0.6`**
35+
36+
37+
| Component | Repository | Revision |
38+
| ---------------------- | ----------------------------------------------------- | -------- |
39+
| `lightspeed-stack-0.6` | `https://github.com/lightspeed-core/lightspeed-stack` | `main` |
40+
| `rag-content-0.6` | `https://github.com/lightspeed-core/rag-content` | `main` |
41+
42+
43+
**Application `lightspeed-core-0.5`**
44+
45+
46+
| Component | Repository | Revision |
47+
| ---------------------- | ----------------------------------------------------- | ------------- |
48+
| `lightspeed-stack-0.5` | `https://github.com/lightspeed-core/lightspeed-stack` | `release/0.5` |
49+
| `rag-content-0.5` | `https://github.com/lightspeed-core/rag-content` | `release/0.5` |
50+
51+
52+
> **Note:** The `rag-content-0.5` component must use the `**rag-content`** repository URL on `**release/0.5**`, mirroring 0.6—not the `lightspeed-stack` URL.
53+
54+
**Takeaway:** The **minor version in the application and component names** (`0.5`, `0.6`) ties the Konflux wiring to a **release branch**. Patch and RC versions are expressed in **image tags and RPA mapping**, not by creating a new application for every `0.6.1` or `0.6.0rc1`.
55+
56+
### 2.2 ReleasePlan per application and connection to RPA
57+
58+
Konflux ties **testing and releasing to the Application**, not to an individual component in isolation. A `**ReleasePlan`** therefore belongs to **exactly one Application**: it describes how **Snapshots** of *that* application are turned into a release (which pipeline runs, what data flows to the managed release service). You need **one `ReleasePlan` per Lightspeed Core application**—for example one for `lightspeed-core-0.5`, one for `lightspeed-core-0.6`, and another when you add `lightspeed-core-0.7`. A single `ReleasePlan` cannot span two applications.
59+
60+
**ReleasePlanAdmission (RPA)** is the **managed-tenant** object that pairs with the developer-side story: it authorizes **which component names** from the release may be published and **to which `registry.redhat.io` repositories** under **which tags**. Practically, each application’s promotion path is “`**ReleasePlan` (dev) ↔ RPA (managed)**” plus the **component mapping** blocks inside the RPA that list the Konflux component names for that release branch (`lightspeed-stack`, `lightspeed-stack-release-0-5`, `rag-content-*`, …) and their target URLs.
61+
62+
When you add a **new** Konflux application for a new minor release branch, you add a **new `ReleasePlan`** for that application **and** extend or duplicate **RPA** so the new application’s components are admitted without colliding with tags owned by other applications (see §2.3). Keep names, `origin`, and `applications` fields in the RPA aligned with the application you intend to ship so the release service matches the right admission record.
63+
64+
### 2.3 ReleasePlanAdmission (RPA)
65+
66+
RPA connects **Konflux components** to **destination repositories** and declares which **component tags** (or tag templates) are written on release.
67+
68+
Example (conceptual YAML):
69+
70+
- **Component `lightspeed-stack`**
71+
- **Repositories:** `registry.redhat.io/lightspeed-core/lightspeed-stack-rhel9`
72+
- **Tags:** `latest`, `0.6-latest`, `0.6-{{ git_sha }}` (and similarly for other release branches as you add them)
73+
- **Component `lightspeed-stack-release-0-5`**
74+
- **Same repository:** `registry.redhat.io/lightspeed-core/lightspeed-stack-rhel9`
75+
- **Tags:** `0.5.1`, `0.5-latest`, `0.5-{{ git_sha }}` (example; patch numbers evolve)
76+
77+
So **multiple Konflux components** can promote into the **same** `lightspeed-stack-rhel9` repository with **different tag sets**, keyed off **which release branch** produced the build.
78+
79+
**Takeaway:** RPA is where you enforce “**this** component build from **this** branch gets **these** tags on **this** registry path.” When you add a new minor release branch or change RC/GA tagging, RPA (and related release plans) must be updated in lockstep with Comet expectations.
80+
81+
---
82+
83+
## 3. Comet (catalog): what users pull
84+
85+
Comet defines **which container images are productized** and **which tags** appear on `registry.redhat.io` for Lightspeed Core users.
86+
87+
### 3.1 Lightspeed Stack
88+
89+
- **Image repository:** `lightspeed-core/lightspeed-stack-rhel9`
90+
- **Architectures:** all supported CPU architectures documented for the product.
91+
- **Version tags** (conceptual set):
92+
93+
| Tag pattern | Meaning |
94+
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
95+
| `latest` | Default “current” GA stream for the product (policy defines what commit/build this tracks). |
96+
| `x.y-latest` | Floating tag for minor **x.y** (e.g. `0.6-latest`, `0.5-latest`). |
97+
| `x.y.z` | Immutable **GA** patch release (e.g. `0.5.2`, `0.6.1`). |
98+
| `x.y.zrcN` | **Release candidate** for a given patch (e.g. `0.6.0rc1`). The notes abbreviate this as `x.y.z"rcZZ"`; the intended form is `**x.y.zrcZZ`**. |
99+
100+
101+
### 3.2 Lightspeed RAG Tool (and GPU flavors)
102+
103+
Multiple repositories follow the same **tag rules** as above, for example:
104+
105+
- `lightspeed-core/rag-tool-cpu-rhel9`
106+
- `lightspeed-core/rag-tool-cuda-12.9-rhel9`
107+
- `lightspeed-core/rag-tool-<gpu-flavor>-rhel9`
108+
109+
**GPU flavor naming** mirrors RHAI base images, for example:
110+
111+
- `rhai/base-image-cuda-12.9-rhel9`, `cuda-13.0`, `rocm-6.4`, `rocm-7.0`, `tpu`, `neuron`, `spyre`, etc.
112+
113+
**Takeaway:** Comet is the **customer-facing contract** (image names + tags). Konflux and RPA exist to **populate** those repositories consistently.
114+
115+
---
116+
117+
## 4. How releases work in practice
118+
119+
### 4.1 Snapshot selection and creating a `Release` for an Application
120+
121+
Konflux promotes images only after you explicitly tie a **known-good Application state** to a `**Release`**. That state is recorded in a `**Snapshot**` custom resource: for a given **Application** (for example `lightspeed-core-0.6`), the Snapshot lists **which components** are in scope and **which built image** (digest) each one contributes for this promotion. A micro or minor ship for that branch always goes through **pick Snapshot → create `Release`** in that application’s workspace.
122+
123+
**Where Snapshots come from**
124+
125+
- Snapshots are typically **produced by automation** when integration or release-prep pipelines for that **Application** succeed (all required components built and tests you configured have passed). The exact trigger is defined in your Konflux pipeline and integration setup.
126+
- You can also **inspect existing Snapshots** in the namespace at any time; each Snapshot is a candidate “bill of materials” for one promotion.
127+
128+
**How to select the Snapshot**
129+
130+
1. Open the Konflux **Application** you are shipping (e.g. `**lightspeed-core-0.6`** for the 0.6 release branch).
131+
2. Go to the **Snapshots** view for that application (Konflux UI) or list Snapshot objects in your **workspace namespace**, e.g. `kubectl get snapshots -n <your-workspace-namespace>`.
132+
3. Choose the Snapshot whose **component entries** match the commits and image digests you intend to release (compare Git revision, pipeline run, or digests to your ticket / build record). Only Snapshots that belong to **this** Application should be used; do not point a `Release` at a Snapshot from another application.
133+
134+
**How to create the `Release`**
135+
136+
1. Confirm the `**ReleasePlan**` name for this Application (one plan per application; §2.2)—for example the plan wired to `lightspeed-core-0.6`.
137+
2. Create a `**Release**` resource in the **developer workspace namespace** where the Application and `ReleasePlan` live. The `Release` must reference **by name**:
138+
- the `**ReleasePlan`** to run (defines the release pipeline and handoff to the managed service), and
139+
- the `**Snapshot**` you selected above (the frozen set of images for this promotion).
140+
3. Use either the Konflux **UI flow** (“create release” from the chosen Snapshot) or `**kubectl` / `oc apply`** with a manifest; field names and optional labels (author, automated vs manual) are spelled out in Red Hat’s **[Creating a release](https://konflux.pages.redhat.com/docs/users/releasing/create-release.html)** (public mirror: [konflux-ci.dev](https://konflux-ci.dev/docs/releasing/create-release/)).
141+
142+
**After you create the `Release`**
143+
144+
The Konflux **release service** reconciles the `Release`, pairs it with **ReleasePlanAdmission** (§2.3) on the managed side, runs the release pipeline, and—on success—publishes images to `registry.redhat.io` with the tags your RPA allows. If the pipeline fails, fix the underlying issue, obtain or wait for a **new Snapshot**, and create a **new `Release`**; you do not mutate the old Snapshot to “retry” a promotion.
145+
146+
**New tags must appear in the RPA**
147+
148+
The admission record is tag-driven: each component block lists `**componentTags`** (and repositories) the release is **allowed** to write. When you ship a **new** tag value for the first time—typically a new **immutable** GA or RC tag (`0.6.1`, `0.6.0rc1`, …), or a deliberate change to which **floating** tags are updated—you must **add or adjust those tag strings in the RPA** for every affected Konflux component **before** the managed pipeline can succeed (or in the same approved change train as the `Release`, per your process). If the tag is missing from the admission mapping, the release may **fail** or **skip** writing that tag even when the `**Snapshot`** and `**Release**` are otherwise correct. Comet must already allow that tag shape for the product image if policy requires it.
149+
150+
### 4.2 Micro releases (patch and RC)
151+
152+
**Patch GA** (e.g. `0.5.2`, `0.6.1`) and **RC** (e.g. `0.6.0rc1`) are **micro releases** on an **existing** minor release branch.
153+
154+
Typical flow:
155+
156+
1. **Git**: Tag or release-branch policy on the correct branch (`release/0.5` for 0.5.x, `main` or a release branch for 0.6.x—follow your team’s branch rules).
157+
2. **Konflux**: The **same** application/components for that branch (`lightspeed-core-0.5` / `lightspeed-stack-0.5`, etc.) pick up the new commit from the configured revision.
158+
3. **Build & test**: Pipelines produce candidate images for that component; integration completes so a **Snapshot** exists for that Application (§4.1).
159+
4. **RPA tags**: Update **ReleasePlanAdmission** so `**componentTags`** for each shipping component include every **new** tag the pipeline must write for this micro release (immutable patch/RC and any floating-tag changes); see §4.1 and §2.3.
160+
5. **Select Snapshot and create `Release`**: Follow §4.1 for the correct Application (`lightspeed-core-0.5` or `lightspeed-core-0.6`) using the Snapshot that captures those builds.
161+
6. **Verify registry tags**: When the release pipeline succeeds, confirm the new **immutable** tag (`0.5.2`, `0.6.0rc1`, …) and **floating** tags (`0.5-latest`, `0.6-latest`, `latest` if appropriate) on `registry.redhat.io` match policy. If something is missing, check RPA coverage before retrying with a new Snapshot/`Release` (the example in §2.3 shows a concrete `0.5.1` under `lightspeed-stack-release-0-5`; after shipping `0.5.2`, that mapping evolves per release engineering rules).
162+
163+
You **do not** create a new Konflux application for each `0.6.0rc1` or `0.5.2`; you reuse the **0.6** or **0.5** application and drive promotion with **Snapshot → `Release` → `ReleasePlan` / RPA** (§2.2–§2.3).
164+
165+
### 4.3 Minor releases (new minor branch, e.g. 0.7)
166+
167+
A **minor** bump (e.g. **0.7**) means a **new maintained API/product stream** carried on a new **release branch** (Git and Konflux application for that minor). That usually implies:
168+
169+
1. **Branch promotion for the previous “current” branch**
170+
When `main` becomes **0.7** development, the **0.6** work should be maintained on a branch such as `**release/0.6`** (analogous to `release/0.5` today).
171+
2. **New Konflux application for the new branch**
172+
Create `**lightspeed-core-0.7`** (names illustrative) with components:
173+
- `lightspeed-stack-0.7` → `lightspeed-stack` @ `**main**`
174+
- `rag-content-0.7` → `rag-content` @ `**main**`
175+
3. **Retarget the previous branch’s application**
176+
Update `**lightspeed-core-0.6`** components so revisions point to `**release/0.6**` (instead of `main`) for both repos—mirroring how **0.5** is wired today.
177+
4. **Comet**
178+
Ensure catalog entries and tag patterns cover `**0.7-*`** (`0.7-latest`, future `0.7.z`, `0.7.zrcN`) alongside existing release branches.
179+
5. **RPA**
180+
- Add (or split) **component mappings** and `**componentTags`** so 0.7 builds may publish tags such as `0.7-latest`, `0.7-{{ git_sha }}`, and eventually `**0.7.z**` / `**0.7.zrcN**`, without clobbering `0.6-*` or `0.5-*`. Every tag the release pipeline should write for a new minor must be **listed in the RPA** for the corresponding Konflux component names (§2.3).
181+
- Decide how `**latest`** moves: usually it tracks the **newest supported default release branch** (often the newest minor GA); document that policy with release management.
182+
6. **Release plans / admissions**
183+
Duplicate or parameterize any per-branch `**ReleasePlan` / RPA** pair (§2.2–§2.3) so each branch can ship on its own cadence.
184+
7. **First `Release` on the new application**
185+
When `**lightspeed-core-0.7`** has a passing integration Snapshot, follow **§4.1** in that application’s workspace: select that Snapshot and create a `**Release`** referencing it and the **0.7** `ReleasePlan`. `**lightspeed-core-0.6`** continues to ship only from its own Snapshots and `ReleasePlan`; never mix applications in one `Release`.
186+
187+
**Summary table**
188+
189+
190+
| Event | Git | Konflux application | Components / revisions | Comet / RPA / promotion |
191+
| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
192+
| 0.6.1 patch | Commits on `release/0.6` or policy branch | Keep `lightspeed-core-0.6` | Same component names; revision still **that release branch** | **RPA:** add `0.6.1` (and tag policy updates) → **Snapshot** → `**Release`** (§4.1) |
193+
| 0.6.0rc1 | RC tags/commits on 0.6 branch | Same | Same | **RPA:** allow `0.6.0rc1` (and RC policy tags) → **Snapshot** → `**Release`** |
194+
| Open 0.7 on `main` | Create `**release/0.6**`, move 0.6 work there; `main` → 0.7 | Add `**lightspeed-core-0.7**`; keep `**lightspeed-core-0.6**` | 0.7 components → `main`; 0.6 components → `**release/0.6**` | New `**ReleasePlan` / RPA** for 0.7; Comet `0.7-*`; first 0.7 ship via §4.1 on the new app |
195+
196+
197+
---
198+
199+
## 5. Checklist for operators
200+
201+
- **RPA:** For each ship, extend `**componentTags`** (and any related admission rules) so every **new** tag the release should write is explicitly allowed before or with the `**Release`** (§4.1, §2.3).
202+
- For each ship, select the correct **Application `Snapshot`**, then create a `**Release**` that references that Snapshot and the Application’s `**ReleasePlan**`, per §4.1 and [Creating a release](https://konflux.pages.redhat.com/docs/users/releasing/create-release.html).
203+
- Each **Application** for a minor release branch has its own `**ReleasePlan`** (§2.2) and matching **RPA** (§2.3) so promotions admit only that application’s components and intended tag policy.
204+
- Application name and component names include the **minor release branch** (`0.5`, `0.6`, `0.7`).
205+
- Each component’s **Git URL and revision** match the repo and **release branch** for that application.
206+
- Comet lists every **user-facing** repository and allowed **tag shapes**.
207+
- RPA maps each **promoting component** to the correct `**registry.redhat.io/...`** path and **tag set** (`latest`, `x.y-latest`, `x.y.z`, `x.y.zrcN`, `x.y-{{ git_sha }}` as applicable).
208+
- On a **new minor**, create the **new application**, **retarget** the old branch’s components to `**release/x.y`**, and update **RPA + `latest`** policy explicitly.
209+
210+
---
211+
212+
## 6. Related links
213+
214+
- [Konflux: Creating a release](https://konflux.pages.redhat.com/docs/users/releasing/create-release.html) — selecting a Snapshot and creating a `Release` (§4.1).
215+
216+
If internal Konflux YAML or Comet bundle sources live in other repositories, link them here once their locations are fixed so this document stays the single narrative entry point.

0 commit comments

Comments
 (0)