RedBear-OS/local/docs/repo-governance.md

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-bluetooth-experimental
• redbear-desktop
• redbear-full
• redbear-wayland
• 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.

6. Resilience policy: local-first package sources

• Red Bear builds must remain resilient when access to upstream Redox infrastructure is degraded or unavailable.
• Local package/source copies are the default operational source of truth for builds.
• Upstream fetch/refresh is opt-in and must be explicitly requested by the operator (for example via an explicit --upstream workflow).
• After an explicit upstream refresh, local durable overlays (local/patches, local/recipes) stay authoritative until a conscious reevaluation/promotion decision is made.

Profile Intent

redbear-minimal

Primary validation baseline: console, storage, package flow, and wired networking.

redbear-bluetooth-experimental

First bounded Bluetooth validation profile: explicit-startup, USB-attached, BLE-first, and experimental only.

redbear-desktop

Supplementary integration support profile for shared Red Bear runtime services beneath the tracked KWin target.

redbear-full

Expanded integration slice that includes more runtime pieces and graphics-path bring-up beneath the tracked KWin target.

redbear-wayland

Dedicated Wayland runtime validation profile layered above the current Red Bear service baseline and subordinate to the tracked KWin direction.

redbear-kde

Dedicated KDE/Plasma bring-up profile and tracked forward desktop target.

redbear-live

Live and recovery variant layered on top of the tracked KWin desktop target.

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.