Add documentation governance docs
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
@@ -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.
|
||||
@@ -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.”
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user