vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record python harness migration; drop superseded policy docs

Browse Source 
- 06-BUILD-SYSTEM-SETUP: note which QEMU proof scripts use
  qemu-login-expect.py vs host expect
- 01-REDOX-ARCHITECTURE, LOCAL-FORK-SUPREMACY-POLICY,
  SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN, UPSTREAM-SYNC-PROCEDURE:
  sync with current fork-model and sync-procedure state
- Delete archived/SOURCE-ARCHIVAL-POLICY.md and
  fork-push-status/2026-07-12-Round-5-phase-4.1.md — superseded by the
  current local-fork model docs and newer fork-push-status rounds
- config/redbear-mini.toml: trailing newline
This commit is contained in:
vasilito
2026-07-20 09:06:25 +09:00
parent cb94e82502
commit 923697887c
8 changed files with 52 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files
config/redbear-mini.toml
+1
View File
@@ -610,3 +610,4 @@ cmd = "ptyd"
# stack). See ptyd/src/main.rs: it is on the SchemeDaemon/ready_with_fd path.
type = { scheme = "pty" }
"""
docs/01-REDOX-ARCHITECTURE.md
+6
View File
@@ -143,6 +143,12 @@ usbhidd (USB HID), inputd (input multiplexor)
## 4. Orbital Display Server
> **Note (2026-07-20):** Orbital is Redox's *reference* display server, documented here as
> architecture background. It is **not** Red Bear's desktop direction — Red Bear targets a
> Wayland compositor path (KWin) on top of DRM/KMS. See
> `../local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop plan and
> `../local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` for the Wayland subsystem path.
Orbital is Redox's display server, window manager, and compositor — all in one userspace daemon.
### Window Creation (via Scheme)
docs/06-BUILD-SYSTEM-SETUP.md
+7
View File
@@ -60,6 +60,13 @@ sudo apt-get install --assume-yes \
xdg-utils xxd zip zstd qemu-system-x86 qemu-kvm
```
> **QEMU test harnesses:** the login-based QEMU proof scripts drive the guest over its
> serial console. Most still use the host `expect` package (listed above). The low-level
> controller proofs (`test-ps2-qemu.sh`, `test-timer-qemu.sh`, `test-iommu-qemu.sh`,
> `test-usb-storage-qemu.sh`) and a growing set of runtime proofs instead use
> `local/scripts/qemu-login-expect.py`, a standard-library-only Python replacement that
> needs no `expect` install. The system `expect` package remains required for the rest.
#### Fedora
```bash
local/docs/LOCAL-FORK-SUPREMACY-POLICY.md
+1 -1
View File
@@ -239,7 +239,7 @@ For relibc/redox-rt specifically:
## Related Documents
- `local/AGENTS.md` — full Red Bear agent guidance (branches, submodules, durability)
- `local/docs/archived/archived/SOURCE-ARCHIVAL-POLICY.md` — how sources are frozen and archived
- `AGENTS.md` (repo root) § RELEASE MODEL — how sources are frozen and archived
- `local/docs/PATCH-GOVERNANCE.md` (referenced in `local/AGENTS.md`) — how patches
are rebased and applied
- `README.md` (project root) — high-level description including the fork model
local/docs/SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN.md
+7 -1
View File
@@ -3,7 +3,13 @@
**Date:** 2026-07-08
**Branch:** 0.3.1
**Source of truth:** Linux kernel 7.1 (`local/reference/linux-7.1/`)
**Status:** Authoritative — Phase 1 COMPLETE (2026-07-08 verification), Phase 2 partially done
**Status:** Historical plan — Phase 1 COMPLETE (2026-07-08), Phase 2 partially done,
Phase 3.1 upstream sync COMPLETE (2026-07-19: all 9 forks pass
`verify-fork-functions.sh`; base/kernel/relibc hand-merged onto latest upstream,
see `local/docs/fork-push-status/`). Sections describing Phase 1 WIP states
(32 uncommitted changes, prefix staleness detection, version drift to +rb0.3.1)
are resolved and retained for history. Current stability work is tracked in
`CONSOLE-TO-KDE-DESKTOP-PLAN.md` and the subsystem plans.
## Relationship to Other Plans
local/docs/UPSTREAM-SYNC-PROCEDURE.md
+30 -13
View File
@@ -714,21 +714,36 @@ This applies to:
- Build system patches and scripts
- Any file under `local/` or `config/redbear-*`
### driver-manager: Upstream Not Ready
### driver-manager: Deferred (consolidated onto pcid-spawner, 2026-07-20)
**Status:** Red Bear internal project. Upstream Redox does NOT have an equivalent.
**Status:** Red Bear internal project, currently **deferred**. Upstream Redox
does NOT have an equivalent.
`driver-manager` (`local/recipes/system/driver-manager/`) is a combined PCI
enumeration + driver matching + hotplug daemon that replaces the upstream
`pcid + pcid-spawner` pair. It was developed because upstream's PCI driver
launching was not ready for Red Bear's needs (advanced driver matching via
`/lib/drivers.d/*.toml`, ACPI device enumeration, hotplug event handling).
enumeration + driver matching + hotplug daemon intended to eventually replace
the upstream `pcid + pcid-spawner` pair. It was developed because upstream's
PCI driver launching was not ready for Red Bear's needs (advanced driver
matching via `/lib/drivers.d/*.toml`, ACPI device enumeration, hotplug event
handling).
**As of 2026-07-20 (Task 3 consolidation), PCI driver spawning is consolidated
on `pcid-spawner`.** The driver-manager migration was stalled: it was written
and packaged, but never actually wired in — its `00_driver-manager.service`
ran `cmd="pcid-spawner"` (the legacy binary), while the base recipe's
`00_pcid-spawner.service` (`oneshot_async`) was the live spawner. Both
services launched `pcid-spawner` asynchronously, so `pcid-spawner` started
TWICE and raced to spawn the same drivers. The consolidation dropped the
unused `driver-manager = {}` package and the duplicate
`00_driver-manager.service`, and pointed `13_driver-params.service`
`requires_weak` at `00_pcid-spawner.service`. The driver-manager recipe
source is kept for the future migration.
**Upstream may provide its own solution in the future.** If and when upstream
Redox offers a concrete, working replacement that matches or exceeds
driver-manager's capabilities, notify the user for a route decision.
Until then, `driver-manager` is the canonical PCI driver orchestration path.
driver-manager's capabilities — or when Red Bear completes the driver-manager
migration — notify the user for a route decision. Until then, `pcid-spawner`
(the base recipe's `00_pcid-spawner.service`, `oneshot_async`) is the sole
PCI driver spawner.
### Systemic Sync Flaw (2026-06 Incident)
@@ -759,12 +774,14 @@ were silently dropped because upstream doesn't have them.
1. `pcid` creates `/scheme/pci` (PCI bus enumeration)
2. `pcid-spawner` reads `/scheme/pci` and launches drivers per `pcid.d/*.toml`
**Red Bear model (0.2.3 and forward):**
**Red Bear model (current, since the 2026-07-20 consolidation):**
1. `pcid` creates `/scheme/pci` (initfs service `35_pcid.service`)
2. `pcid-spawner --initfs` launches critical boot drivers (initfs)
3. `driver-manager --hotplug` handles full driver matching + hotplug (rootfs)
3. `pcid-spawner` (the base recipe's `00_pcid-spawner.service`,
`oneshot_async`) is the sole PCI driver spawner on the rootfs side
**Key learning:** Without `35_pcid.service` in initfs, `/scheme/pci` is never
created, and BOTH `pcid-spawner` (initfs and rootfs) fail with ENODEV. This
was masked in 0.2.3 because driver-manager does its own PCI enumeration via
`redox_driver_pci` and doesn't depend on `/scheme/pci`.
was masked in 0.2.3 because driver-manager did its own PCI enumeration via
`redox_driver_pci` and didn't depend on `/scheme/pci`. driver-manager is now
deferred (see above); the live path is `pcid` + `pcid-spawner`.
local/docs/archived/SOURCE-ARCHIVAL-POLICY.md
-91
View File
@@ -1,91 +0,0 @@
# Source Archival Policy — Red Bear OS
**Effective:** 2026-04-29
**Status:** Active / Enforceable
## Principle
Every source archive exported to `sources/<target-triple>/` must include the package version
number in its filename, and must contain the fully-patched source tree as it was used during the
build. No archive may be named solely by category — every archive filename must carry a version
qualifier.
## Naming Convention
```
sources/<target-triple>/<category>-<pkgname>-v<version>-patched.tar.gz
```
| Component | Meaning | Example |
|---|---|---|
| `<category>` | Recipe category directory | `core`, `libs`, `wip` |
| `<pkgname>` | Package name from recipe directory | `base`, `dbus`, `qtbase` |
| `<version>` | Source version from recipe (tar/git rev) | `1.16.2`, `6.11.0`, `463f76b` |
| `patched` | Indicates all recipe patches are applied | always present |
**Examples:**
```
core-base-v463f76b-patched.tar.gz
wip-services-dbus-v1.16.2-patched.tar.gz
wip-qt-qtbase-v6.11.0-patched.tar.gz
wip-qt-qtdeclarative-v6.11.0-patched.tar.gz
core-relibc-v2025-10-03-patched.tar.gz
```
## Version Sources
The version is extracted from the recipe's `[source]` block:
| Source type | Version extraction |
|---|---|
| `tar = "https://.../pkg-X.Y.Z.tar.xz"` | Extract `X.Y.Z` from URL |
| `git = "https://...repo.git"` + `rev = "abc123"` | Use git rev short hash (`abc123`) |
| `path = "source"` (local) | Use the recipe's `[source]` section name or a manual version marker |
## Archive Contents
Each versioned archive must contain:
1. The **fully patched source tree** at `recipes/<category>/<pkgname>/source/` — after all `patches = [...]` have been applied
2. The **recipe file** (`recipe.toml`) that defines the build
3. A **metadata file** (`source-info.json`) with: package name, version, source type, patch list, and build date
### Metadata format
```json
{
"package": "dbus",
"version": "1.16.2",
"source_type": "tar",
"source_url": "https://dbus.freedesktop.org/releases/dbus/dbus-1.16.2.tar.xz",
"blake3": "b1d1f22858a8f04665e5dca29d194f892620f00fd3e3f4e89dd208e78868436e",
"patches": ["redox.patch"],
"build_date": "2026-04-29T00:00:00Z",
"target": "x86_64-unknown-redox"
}
```
## Enforcement
- The `packages.txt` manifest in `sources/<target-triple>/` lists all exported packages with versions
- Every CI/documentation run that exports sources must use versioned naming
- An archive without a version number is considered incomplete — it must be regenerated
- The `make sources` target (when created) will auto-generate versioned archives
## Existing Non-Versioned Archives (Migration)
Current archives in `sources/x86_64-unknown-redox/` named like `core-base.tar.gz` are legacy.
They must be migrated to the versioned naming convention on next rebuild:
| Old name | New name |
|---|---|
| `core-base.tar.gz` | `core-base-v463f76b-patched.tar.gz` |
| `core-kernel.tar.gz` | `core-kernel-v<rev>-patched.tar.gz` |
| `core-relibc.tar.gz` | `core-relibc-v<rev>-patched.tar.gz` |
| `libs-mesa.tar.gz` | `libs-mesa-v<ver>-patched.tar.gz` |
## Related
- `../AGENTS.md` — repository structure and durability policy
- `docs/06-BUILD-SYSTEM-SETUP.md` — build system mechanics
- `local/docs/PATCH-GOVERNANCE.md` — patch governance policy
local/docs/fork-push-status/2026-07-12-Round-5-phase-4.1.md
-77
View File
@@ -1,77 +0,0 @@
# Fork-Branch Push Status — 2026-07-12 (Round 5, Phase 4.1)
## Pushed (via push-fork-branches.sh --execute, Round 5 Phase 4.0)
| Fork | Before | After | Origin SHA -> Local SHA | Status |
|------------|---------|---------|--------------------------|--------|
| installer | 61/0 | PUSHED | 6afa6e5..8294ecb | OK |
| kernel | 49/0 | PUSHED | 77e745a..b2a92287 | OK |
| syscall | 1/0 | PUSHED | c8bc43a..6e4e5bd | OK |
| libredox | 69/11 | PUSHED | 52c324c..b99b204 | OK |
| userutils | 202/12 | PUSHED | ac3cff2..0dc0cb7 | OK |
| relibc | 3437/60 | PUSHED | bae63d9..d157c227 | OK |
All 6 force-pushes used `--force-with-lease=<old-sha>` to prevent
clobbering concurrent work we hadn't seen. All target refs now reflect
the operator's own Red Bear work (Rounds 0-4 patches + cleanup
commits) rather than the abandoned +rb0.2.5/+rb0.3.0 upstream-tracking
era.
## PUSH BLOCKED — needs operator action
| Fork | Ahead | Behind | Block Reason |
|------------|-------|--------|--------------|
| base | 2569 | 190 | gitea `receive.shallowUpdate=true` blocks new deeper pushes |
The gitea server's `receive.shallowUpdate` config (default true on
gitea) refuses to accept a push that would deepen the existing
submodule/base ref. Our local base has 2569 commits, but the server
only has a shallow clone of base (probably from when the submodule
was first added).
**Operator actions to unblock base push:**
1. Disable receive.shallowUpdate on the gitea repo
(`gitea admin settings update receive.shallowUpdate=false` in
the gitea admin, or set via gitea config.toml per-repo)
2. OR: push via gitea's web UI (gitea can deepen the ref through
its admin interface)
3. OR: force-push from a server-side clone where the receiver
has access to deepen the ref
Per AGENTS.md "BRANCH AND SUBMODULE POLICY" agents MUST NOT push
without operator review. The force-push for base is NOT attempted
automatically. This is a known operator-side blocker.
## PUSH DEFERRED (Phase 2.4+ work)
| Fork | Ahead | Behind | Reason |
|------------|-------|--------|--------|
| bootloader | 11 | 128 | 927 vs 77 file divergence, requires `upgrade-forks.sh bootloader` |
Per fork-upstream-map.toml, bootloader is marked 'diverged' for a
reason: 856 files of legitimate Red Bear work that doesn't map to
upstream 1.0.0. The 128 commits behind on origin are upstream
bootloader evolution (Add support for live disk, Reduce prints from
UEFI bootloader, Get aarch64 UEFI bootloader building, etc.) —
none of which the Red Bear fork should accept (we have our own
decision to keep the 0.1.0-based legacy code path).
When upgrade-forks.sh bootloader is finally run, the operator
must decide:
(a) rebase local onto a newer upstream bootloader tag (replacing
the 856-file Red Bear work) — likely breaks the Red Bear
0.1.0 compatibility that's been preserved since 2025
(b) accept base 128-behind + base-specific Red Bear work (so
we get the live-disk support but keep our divergence)
(c) keep current state (don't push, maintain fork supremacy)
## Audit notes
- After all 6 force-pushes, the parent RedBear-OS `0.3.1` branch
has its parent-side gitlinks updated to the new SHAs. No further
parent-side commits required for the fork-push part of Phase 4.
- Fork-side work: each fork's `master` branch (or `0.3.1` for kernel)
is the source of truth. Round 0-4 patches are preserved as
properly-committed changes inside the forks.