From f838cfc171bcfa4842881567b2944222464fbe9b Mon Sep 17 00:00:00 2001 From: Vasilito Date: Wed, 15 Apr 2026 12:57:07 +0100 Subject: [PATCH] Add documentation governance docs Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- .../docs/PROJECT-DOCUMENTATION-ASSESSMENT.md | 235 ++++++++++++++++++ local/docs/SCRIPT-BEHAVIOR-MATRIX.md | 55 ++++ local/docs/WIP-MIGRATION-LEDGER.md | 67 +++++ 3 files changed, 357 insertions(+) create mode 100644 local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md create mode 100644 local/docs/SCRIPT-BEHAVIOR-MATRIX.md create mode 100644 local/docs/WIP-MIGRATION-LEDGER.md diff --git a/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md b/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md new file mode 100644 index 00000000..c802182e --- /dev/null +++ b/local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md @@ -0,0 +1,235 @@ +# Project Documentation Assessment + +## Purpose + +This document assesses the current Red Bear OS documentation set after the repository-model and WIP +ownership policy updates. + +The goal is not only to list documents. The goal is to answer: + +- which docs are canonical and current +- which docs are still useful but historical +- which areas are well-covered +- which areas still have duplication, stale wording, or split ownership + +## Executive Summary + +The documentation set is now **directionally strong** and much clearer than before about Red Bear’s +relationship to upstream Redox. The repository-level model is now visible in the root docs, +implementation plan, overlay guide, and relibc-specific planning notes. + +The strongest documentation theme is now the **overlay discipline**: + +- RedBearOS is documented as an overlay distribution on top of Redox +- upstream-owned sources are documented as refreshable working copies +- durable Red Bear state is documented as living in `local/patches/`, `local/recipes/`, + `local/docs/`, and tracked Red Bear configs +- fast-moving upstream components such as relibc are documented with an upstream-first rule +- upstream WIP is now documented as a local-project trigger for Red Bear until upstream promotes it + +That is the right long-term maintenance model. + +The main remaining weakness is **documentation fragmentation**. There is now enough good material, +but some topics are spread across too many files, and some older public docs still speak in a more +fork-oriented or historically WIP-oriented voice than the newer overlay model. + +## Strong Areas + +### 1. Repository ownership model + +This is now one of the strongest-documented parts of the project. + +The model is visible in: + +- `AGENTS.md` +- `local/AGENTS.md` +- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` +- `docs/README.md` + +The key message is now consistent: Red Bear is an overlay on top of Redox, not a permanent fork of +every upstream-owned source tree. + +### 2. relibc maintenance logic + +The relibc docs are much stronger than before because they now document both: + +- the **technical completeness** story +- the **preservation/reapply** story + +The most important improvement is that relibc work is no longer described only as source changes in +`recipes/core/relibc/source/`. It is now also described as a patch-carrier workflow under +`local/patches/relibc/`, which is the right long-term maintenance framing. + +### 3. Subsystem planning depth + +USB, Wi-Fi, Bluetooth, IRQ/low-level controller work, relibc IPC, and AMD/graphics all have +substantial focused planning material under `local/docs/`. + +This is good. These are the areas where Red Bear differs most strongly from upstream, so deep local +planning documents are appropriate. + +### 4. Public implementation plan + +`docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` is now doing the right job as the canonical public +execution-order and repository-model document. It no longer reads like only a historical hardware +roadmap. + +## Weak Areas + +### 1. Historical docs still bleed into current-state reading + +The older `docs/01`–`docs/05` files still contain valuable architecture and rationale, but some of +them still carry old assumptions such as: + +- “WIP means upstream ownership is good enough” +- “missing / not started” wording for areas that are now partially or substantially implemented +- public-facing framing that predates the current overlay-policy language + +They are no longer wrong in all details, but they are not all equally safe as current-state guides. + +### 2. WIP ownership policy is newly documented, but not yet propagated everywhere + +The new WIP rule is now present in the repository model and WIP-specific guide, but there are still +older docs and notes that talk about `recipes/wip/` as if it were simply the place where future +shipping work lives. + +That is no longer the full policy. For Red Bear, upstream WIP should now be read as: + +- useful upstream input +- not yet a stable shipping source of truth +- candidate for local takeover until upstream promotes it + +This wording should be propagated further over time, especially in older public roadmap docs. + +### 3. Script awareness is documented more than enforced + +The scripts now explain the overlay/WIP model better, but some of them are still operationally +neutral. They do not yet encode every policy distinction automatically. + +Examples: + +- `fetch-all-sources.sh` documents the rule, but still fetches upstream WIP sources as raw inputs +- `sync-upstream.sh` documents the rule, but its conflict checks are still strongest for build-system + patches, not all subsystem overlays +- `apply-patches.sh` documents the rule, but its actual symlink/application logic is still strongest + for the established overlay paths and not for all possible future WIP-local migrations + +This is acceptable for now, but it means “policy-aware” is currently stronger in docs than in full +automation. + +### 4. No single canonical doc-index for current-vs-historical status + +`docs/README.md` helps, but there is still no one-page matrix saying, for every major document: + +- canonical current-state source +- architectural rationale only +- historical plan +- Red Bear overlay-specific supplement + +That would reduce confusion significantly. + +## Canonicality Assessment + +### Canonical current-state / policy docs + +- `AGENTS.md` +- `local/AGENTS.md` +- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` +- `docs/README.md` +- subsystem plans under `local/docs/` that cover active Red Bear-owned workstreams + +### Canonical technical local overlays for active subsystems + +- `local/docs/RELIBC-COMPLETENESS-AND-ENHANCEMENT-PLAN.md` +- `local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` +- `local/docs/QT6-PORT-STATUS.md` +- `local/docs/USB-IMPLEMENTATION-PLAN.md` +- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` +- `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` +- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` + +### Valuable but partially historical docs + +- `docs/01-REDOX-ARCHITECTURE.md` +- `docs/02-GAP-ANALYSIS.md` +- `docs/03-WAYLAND-ON-REDOX.md` +- `docs/04-LINUX-DRIVER-COMPAT.md` +- `docs/05-KDE-PLASMA-ON-REDOX.md` + +These should still be treated as useful references, but their top-level status notes must continue to +warn readers when current implementation has moved ahead of the original text. + +## Documentation Gaps Still Worth Fixing + +### Gap 1 — Canonical document-status matrix + +**Status:** addressed. + +The repo now has a visible document-status matrix in `docs/README.md` that marks the major docs as: + +- current policy +- current subsystem plan +- architecture reference +- historical roadmap + +### Gap 2 — WIP migration ledger + +**Status:** addressed. + +The repo now has a compact WIP ownership ledger in `local/docs/WIP-MIGRATION-LEDGER.md` that tracks +which major areas are currently in which state: + +- still consumed directly from upstream WIP +- mirrored locally and shipped from `local/recipes/` +- promoted upstream again, so Red Bear prefers upstream + +This is especially useful for Qt/KDE/Wayland-adjacent work. + +### Gap 3 — Script behavior matrix + +**Status:** addressed. + +The repo now has a concise script behavior matrix in `local/docs/SCRIPT-BEHAVIOR-MATRIX.md` +covering: + +- what `sync-upstream.sh` does and does not handle +- what `apply-patches.sh` applies and what it only symlinks +- what `build-redbear.sh` assumes about local overlays +- what `fetch-all-sources.sh` means for upstream WIP versus local recipes + +This behavior is now centralized instead of being only inferable from scripts. + +### Gap 4 — Public/current Qt and Wayland split + +**Status:** addressed. + +Qt and Wayland status is still spread across multiple detailed docs, but the repo now has a +canonical current-state summary in `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` to anchor the +current build/runtime truth while the older public docs remain useful as history/rationale: + +- `docs/03-WAYLAND-ON-REDOX.md` +- `docs/05-KDE-PLASMA-ON-REDOX.md` +- `local/docs/QT6-PORT-STATUS.md` +- recipe-local notes + +## Recommended Next Documentation Moves + +1. Continue pruning local relibc overlays when upstream truly covers them — but only after the + fresh-source reapply + rebuild path proves it. +2. Keep the WIP migration ledger current as upstream WIP areas are promoted or replaced. +3. Extend the same upstream-first cleanup discipline to other fast-moving system packages, + especially the desktop stack. +4. Periodically re-check older public roadmap docs to ensure their historical notes remain visible + and accurate. + +## Bottom Line + +The project documentation is now fundamentally pointed in the right direction. + +Its strongest improvement is conceptual clarity: Red Bear is now documented as an overlay on top of +Redox, not as a permanently hand-maintained fork of every moving part. The relibc work in +particular now has both a technical story and a preservation story. + +The biggest remaining weakness is not missing information; it is **distribution of information**. +There is enough good documentation now, but some of it still needs a cleaner canonical index and a +more explicit split between current policy, current subsystem plans, and historical roadmaps. diff --git a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md new file mode 100644 index 00000000..42c4396a --- /dev/null +++ b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md @@ -0,0 +1,55 @@ +# Red Bear OS Script Behavior Matrix + +## Purpose + +This document centralizes what the main repository scripts do and do not handle under the Red Bear +overlay model. + +The goal is to remove guesswork from the sync/fetch/apply/build workflow. + +## Matrix + +| Script | Primary role | What it handles | What it does **not** guarantee | +|---|---|---|---| +| `local/scripts/sync-upstream.sh` | Refresh top-level upstream repo state | fetches upstream, reports conflict risk, rebases repo commits, reapplies build-system overlays via `apply-patches.sh` | does not automatically solve every subsystem overlay conflict; does not by itself make upstream WIP recipes safe shipping inputs | +| `local/scripts/apply-patches.sh` | Reapply durable Red Bear overlays | applies build-system patches, relinks recipe patch symlinks, relinks local recipe overlays into `recipes/` | does not fully rebase stale patch carriers; does not validate runtime behavior; does not decide WIP ownership for you | +| `local/scripts/build-redbear.sh` | Build Red Bear profiles from upstream base + local overlay | applies overlays, builds cookbook if needed, validates profile naming, launches the actual image build | does not guarantee every nested upstream source tree is fresh; does not replace explicit subsystem/runtime validation | +| `scripts/fetch-all-sources.sh` | Fetch recipe source inputs for builds | downloads recipe sources for upstream and local recipes, reports status/preflight, supports config-scoped fetches | does not mean fetched upstream WIP source is the durable shipping source of truth | +| `local/scripts/fetch-sources.sh` | Fetch local overlay source inputs | fetches local overlay recipe sources and keeps the local side ready for build work | does not decide whether upstream should replace the local overlay | + +## Policy Mapping + +### Upstream sync + +Use `local/scripts/sync-upstream.sh` when the goal is to refresh the top-level upstream Redox base. + +This is a repository sync operation, not a guarantee that every local subsystem overlay is already +rebased cleanly. + +### Overlay reapplication + +Use `local/scripts/apply-patches.sh` when the goal is to reconstruct Red Bear’s overlay on top of a +fresh upstream tree. + +This is the core durable-state recovery path. + +### Build execution + +Use `local/scripts/build-redbear.sh` when the goal is to build a tracked Red Bear profile from the +current upstream base plus local overlay. + +### Source refresh + +Use `scripts/fetch-all-sources.sh` and `local/scripts/fetch-sources.sh` when the goal is to refresh +recipe source inputs, but do not confuse fetched upstream WIP source with a trusted shipping source. + +## WIP Rule in Script Terms + +If a subsystem is still upstream WIP, the scripts should be interpreted this way: + +- fetching upstream WIP source is allowed and useful, +- syncing upstream WIP source is allowed and useful, +- but shipping decisions should still prefer the local overlay until upstream promotion and reevaluation happen. + +That means “script fetched it successfully” is not the same as “Red Bear should now ship upstream’s +WIP version directly.” diff --git a/local/docs/WIP-MIGRATION-LEDGER.md b/local/docs/WIP-MIGRATION-LEDGER.md new file mode 100644 index 00000000..0a301fcf --- /dev/null +++ b/local/docs/WIP-MIGRATION-LEDGER.md @@ -0,0 +1,67 @@ +# Red Bear OS WIP Migration Ledger + +## Purpose + +This ledger records how Red Bear treats upstream WIP areas under the overlay policy. + +The goal is to keep one compact, current view of whether a major WIP subsystem is: + +- still consumed mainly from upstream WIP, +- mirrored locally and shipped from the Red Bear overlay, +- or mature enough upstream that Red Bear should prefer the upstream version. + +This is a repo-governance document, not a subsystem deep dive. + +## Status Labels + +- **upstream-wip-input** — upstream WIP still exists and is useful as an input/reference, but Red Bear + does not treat it as the durable shipping source of truth +- **local-overlay-owner** — Red Bear currently owns the shipping/integration burden locally +- **mixed-transition** — both upstream WIP and local overlay matter; Red Bear is still evaluating what + to keep locally versus what to prefer upstream +- **prefer-upstream** — upstream is now first-class enough that Red Bear should default to upstream and + keep only a narrow local integration delta if still needed + +## Current Ledger + +| Area | Current status | Current preferred shipping source | Notes | +|---|---|---|---| +| Qt6 base stack (`qtbase`, `qtdeclarative`, `qtsvg`, `qtwayland`) | **mixed-transition** | local overlay + upstream WIP inputs | Upstream WIP remains useful input, but Red Bear still carries recipe/integration fixes and validation locally. | +| KDE Frameworks / Plasma / KWin | **local-overlay-owner** | local overlay | Current KDE/Plasma recipe tree under `local/recipes/kde/` is the practical shipping source for Red Bear. | +| Wayland compositor/session stack | **mixed-transition** | local overlay for shipping decisions | Upstream WIP recipes remain inputs, but runtime-trusted Red Bear delivery still depends on local validation and local recipe ownership where needed. | +| `libinput` / desktop input userland | **mixed-transition** | local decision pending | Upstream WIP recipe exists, but Red Bear still treats this as a local validation and integration concern rather than a trusted upstream shipping surface. | +| `seatd` runtime path | **mixed-transition** | recipe-level decision still local | It builds and is integrated into KDE-facing configs, but runtime trust still trails the packaging story. | +| `redox-driver-sys` | **local-overlay-owner** | local overlay | Red Bear-owned driver substrate. | +| `linux-kpi` | **local-overlay-owner** | local overlay | Red Bear-owned compatibility layer. | +| `redox-drm` / `amdgpu` | **local-overlay-owner** | local overlay | Red Bear-owned graphics/driver work. | +| `firmware-loader` | **local-overlay-owner** | local overlay | Red Bear-owned runtime infrastructure. | +| relibc compatibility overlays | **mixed-transition** | upstream + local overlay | Prefer upstream where available; keep only the overlays that still prove necessary after fresh-source reapply and downstream rebuild. | + +## Decision Rules + +### When to stay local + +Stay local when one or more of the following is true: + +- upstream still marks the recipe/subsystem WIP, +- Red Bear still needs local fixes to build or ship it, +- Red Bear is carrying the validation burden that upstream has not yet established, +- the local version is the only version that currently integrates correctly with tracked Red Bear profiles. + +### When to move back toward upstream + +Prefer upstream when all of the following become true: + +- upstream no longer treats the area as WIP, +- upstream solves the same problem adequately, +- refreshed upstream source + minimal Red Bear integration still rebuilds the affected profiles, +- keeping the local overlay would no longer provide unique value. + +## Review Trigger + +Reevaluate an entry in this ledger whenever: + +- upstream removes WIP status from the recipe/subsystem, +- Red Bear finishes a fresh-source reapply + rebuild proof, +- a local overlay shrinks substantially because upstream caught up, +- or the shipping profile set starts depending on a WIP area more heavily than before.