From 0a6b734071f0f8260ee75c1cc09086d0cd30438f Mon Sep 17 00:00:00 2001 From: Vasilito Date: Tue, 14 Apr 2026 11:43:37 +0100 Subject: [PATCH] Document Phase 1 governance and profile surfaces Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md | 80 ++++++++++++++++---- local/AGENTS.md | 17 +++++ local/docs/PROFILE-MATRIX.md | 50 +++++++++++++ local/docs/repo-governance.md | 87 ++++++++++++++++++++++ 4 files changed, 219 insertions(+), 15 deletions(-) create mode 100644 local/docs/PROFILE-MATRIX.md create mode 100644 local/docs/repo-governance.md diff --git a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md index 2d26823d..3581b89e 100644 --- a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md +++ b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md @@ -247,44 +247,92 @@ Drive the graphical stack through concrete milestones. - Support status is explicit and reproducible. -## Development Phases +## Execution Phases -### Phase A — Structure +### Phase 1 — Repository discipline and profile reproducibility -- Repository rules -- Profile definitions +- Establish repository rules for Red Bear-specific work. +- Make tracked profiles explicit. +- Reduce duplicated profile wiring through shared config fragments. +- Keep build helpers aligned with the tracked profile set. -### Phase B — Minimal system +**Primary targets** + +- `redbear-minimal` +- `redbear-desktop` + +**Acceptance** + +- Profile composition is easier to audit. +- Shared Red Bear service wiring is not copy-pasted across profile files. +- Repository governance and support-language rules are documented. + +### Phase 2 — Minimal system baseline - Boot - Package management - VM networking -### Phase C — Driver base +**Acceptance** + +- `redbear-minimal` remains the primary reproducible validation baseline. + +### Phase 3 — Driver and runtime substrate - Shared driver layer +- Firmware loading +- Input/runtime service prerequisites -### Phase D — Graphics +**Acceptance** -- Wayland +- The driver/runtime substrate needed by graphics and desktop work is explicitly packaged and wired. + +### Phase 4 — Graphics and Wayland path + +- Wayland runtime path - Qt application bring-up +- Profile-level graphics integration -### Phase E — Networking +**Acceptance** -- Wired networking +- At least one profile can carry a coherent graphical session path. + +### Phase 5 — Wired networking and desktop integration + +- Wired networking on real profiles - KDE-visible networking path +- Session-level compatibility surfaces -### Phase F — Desktop +**Acceptance** -- KDE session becomes usable +- Wired networking works in at least one profile with documented limits. -### Phase G — Hardware validation +### Phase 6 — KDE session viability + +- KWin +- Plasma shell +- Session startup packaging + +**Acceptance** + +- KDE session launch is possible with documented limitations. + +### Phase 7 — Hardware validation and support labels - One fully validated profile +- Support matrix and validation evidence -### Phase H — Wi-Fi +**Acceptance** -- Experimental expansion +- Support claims are explicit, reproducible, and tied to a profile. + +### Phase 8 — Wi-Fi expansion + +- Experimental Wi-Fi support for one chipset family first + +**Acceptance** + +- Wi-Fi work remains clearly marked as experimental until validated. ## Task Template @@ -325,3 +373,5 @@ Progress should be measured by working profiles, not theoretical completeness. - [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md) - [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) - [`local/docs/AMD-FIRST-INTEGRATION.md`](../local/docs/AMD-FIRST-INTEGRATION.md) +- [`local/docs/repo-governance.md`](../local/docs/repo-governance.md) +- [`local/docs/PROFILE-MATRIX.md`](../local/docs/PROFILE-MATRIX.md) diff --git a/local/AGENTS.md b/local/AGENTS.md index ec0dae55..e29c8198 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -260,9 +260,26 @@ redbear-live.toml NOTE: redbear-info is the canonical runtime integration report. Keep it updated when Red Bear adds new tools, schemes, services, or hardware integration paths. +redbear-full.toml + └── desktop.toml (mainline) + └── redbear-legacy-base.toml ← Neutralize broken base legacy init scripts + └── redbear-legacy-desktop.toml ← Neutralize broken desktop legacy init scripts + └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring + └── redbear-netctl.toml ← Shared Red Bear network profile files + netctl boot service + +redbear-kde.toml + └── desktop.toml (mainline) + └── redbear-legacy-base.toml ← Neutralize broken base legacy init scripts + └── redbear-legacy-desktop.toml ← Neutralize broken desktop legacy init scripts + └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring + └── redbear-netctl.toml ← Shared Red Bear network profile files + netctl boot service + redbear-minimal.toml └── minimal.toml (mainline) └── base.toml + └── redbear-legacy-base.toml ← Neutralize broken base legacy init scripts + └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring + └── redbear-netctl.toml ← Shared Red Bear network profile files + netctl boot service └── [packages] redbear-release, redbear-hwutils, redbear-netctl, redox-driver-sys, firmware-loader, evdevd, udev-shim ``` diff --git a/local/docs/PROFILE-MATRIX.md b/local/docs/PROFILE-MATRIX.md new file mode 100644 index 00000000..74e3e655 --- /dev/null +++ b/local/docs/PROFILE-MATRIX.md @@ -0,0 +1,50 @@ +# Red Bear OS Profile Matrix + +## Purpose + +This matrix makes the tracked Red Bear profiles explicit so support claims map to a concrete build +target instead of a vague feature list. + +## Validation Labels + +- **builds** — configuration and packages are expected to compile +- **boots** — image is expected to reach a usable boot state +- **validated** — behavior has been tested on the claimed profile +- **experimental** — available for bring-up, but not support-promised + +## Tracked Profiles + +| Profile | Intent | Key Fragments | Current support language | +|---|---|---|---| +| `redbear-minimal` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline | +| `redbear-desktop` | Main Red Bear desktop integration profile without KDE-specific session wiring | `desktop.toml`, `redbear-netctl.toml` | builds | +| `redbear-full` | Expanded graphics/input/Qt integration target | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental runtime path | +| `redbear-kde` | KDE Plasma bring-up profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental desktop path | +| `redbear-live` | Live and recovery image layered on desktop | `redbear-desktop.toml` | builds | + +## Profile Notes + +### `redbear-minimal` + +- First place to validate repository discipline and profile reproducibility. +- Should stay smaller and less assumption-heavy than the graphics profiles. + +### `redbear-desktop` + +- Carries the standard Red Bear desktop-facing package additions. +- Inherits desktop behavior but avoids the heavier KDE session-specific wiring. + +### `redbear-full` + +- Used for broader integration work that combines graphics, input, and Qt runtime pieces. +- Should not be described as fully supported until runtime validation is evidence-backed. + +### `redbear-kde` + +- Dedicated profile for Plasma/KWin session bring-up. +- Keep KDE-specific service wiring here instead of leaking it into the generic desktop profile. + +### `redbear-live` + +- Intended for install, demo, and recovery workflows. +- Should inherit only stable desktop-profile assumptions unless explicitly documented. diff --git a/local/docs/repo-governance.md b/local/docs/repo-governance.md new file mode 100644 index 00000000..bade9847 --- /dev/null +++ b/local/docs/repo-governance.md @@ -0,0 +1,87 @@ +# Red Bear OS Repository Governance + +## Purpose + +This document defines the repository-discipline rules for Red Bear OS so profile work stays +reproducible, reviewable, and upstream-friendly. + +## Core Rules + +### 1. Keep Red Bear work isolated + +- Put Red Bear-specific source, recipes, scripts, and docs under `local/` whenever possible. +- Prefer patch files and symlinks over direct edits to upstream-managed source trees. +- Treat mainline Redox areas as upstream surfaces first, not as the default place for Red Bear + customization. + +### 2. Profiles are the support surface + +Tracked Red Bear profiles are: + +- `redbear-minimal` +- `redbear-desktop` +- `redbear-full` +- `redbear-kde` +- `redbear-live` + +Every user-visible feature should name which profile(s) it belongs to. + +### 3. Validation claims must be explicit + +- `builds` means the package or profile compiles. +- `boots` means the image reaches a real bootable system state. +- `validated` means behavior has been tested on the claimed profile. +- `experimental` means present for bring-up but not support-promised. + +Do not describe compile-only work as supported hardware or a working desktop path. + +### 4. Prefer shared fragments over duplicated profile logic + +- Shared profile file wiring belongs in reusable `config/redbear-*.toml` fragments. +- Avoid copy-pasting identical service definitions or file payloads across multiple Red Bear + profiles. +- Keep profile-specific behavior in the profile file only when the runtime behavior is actually + different. + +### 5. Build helpers must match tracked profiles + +If a profile is tracked in git, helper scripts and docs should either support it directly or state +why it is intentionally excluded. + +## Profile Intent + +### `redbear-minimal` + +Primary validation baseline: console, storage, package flow, and wired networking. + +### `redbear-desktop` + +Main integration profile for desktop-oriented Red Bear services without making KDE the default. + +### `redbear-full` + +Expanded desktop/integration target that includes more runtime pieces and graphics-path bring-up. + +### `redbear-kde` + +Dedicated KDE/Plasma bring-up profile. + +### `redbear-live` + +Live and recovery variant layered on top of the Red Bear desktop path. + +## Change Checklist + +For any substantial Red Bear change, record: + +- objective +- profile impact +- files touched +- validation level (`builds`, `boots`, `validated`, `experimental`) +- known limitations + +## Upstream Sync Discipline + +- Rebase/sync through `local/scripts/sync-upstream.sh`. +- Keep Red Bear-specific diffs easy to audit. +- Update profile docs when config inheritance or package composition changes.