From 95405baf2e147e64c8aa29dcbb4213d3ec5d5fc1 Mon Sep 17 00:00:00 2001 From: Vasilito Date: Tue, 21 Apr 2026 16:15:16 +0100 Subject: [PATCH] Document local-first package sourcing policy Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- README.md | 6 ++++++ docs/06-BUILD-SYSTEM-SETUP.md | 9 ++++++++- local/docs/SCRIPT-BEHAVIOR-MATRIX.md | 11 +++++++++++ local/docs/repo-governance.md | 10 ++++++++++ 4 files changed, 35 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e75bacfe..aab98b41 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,12 @@ relates to Debian: - durable Red Bear state belongs in `local/patches/`, `local/recipes/`, `local/docs/`, and tracked Red Bear configs +Operational resilience policy: + +- package/source usage is local-first by default, +- local copies are used continuously for builds and recovery workflows, +- upstream package refresh is performed only when explicitly requested. + For **upstream WIP recipes specifically**, Red Bear uses a stricter rule: 1. once an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a local project diff --git a/docs/06-BUILD-SYSTEM-SETUP.md b/docs/06-BUILD-SYSTEM-SETUP.md index 9b6ac10c..c3f71b86 100644 --- a/docs/06-BUILD-SYSTEM-SETUP.md +++ b/docs/06-BUILD-SYSTEM-SETUP.md @@ -16,6 +16,13 @@ Build this repository using the Red Bear overlay model: - upstream WIP recipes are useful inputs, but should not automatically be treated as the durable shipping source of truth for Red Bear. +Resilience policy for package/source inputs: + +- default build posture is local-first/offline-capable, +- local copies are used continuously unless upstream refresh is explicitly requested, +- upstream refresh is an explicit operation, not an implicit background requirement for normal + builds. + ## Prerequisites ### System Requirements @@ -260,7 +267,7 @@ cp target/release/myapp ${COOKBOOK_STAGE}/usr/bin/ | `PREFIX_BINARY` | `1` | Use prebuilt toolchain (faster) | | `REPO_BINARY` | `0` | Use prebuilt packages (faster, no compilation) | | `REPO_NONSTOP` | `0` | Continue on build errors | -| `REPO_OFFLINE` | `0` | Don't update source repos | +| `REPO_OFFLINE` | `0` | Don't update source repos; Red Bear policy treats local-first sourcing as the normal operating mode and upstream refresh as explicit opt-in | ### Environment Variables for Recipes diff --git a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md index e8240a08..8ca56877 100644 --- a/local/docs/SCRIPT-BEHAVIOR-MATRIX.md +++ b/local/docs/SCRIPT-BEHAVIOR-MATRIX.md @@ -64,6 +64,17 @@ repo already contains `prefix/x86_64-unknown-redox/sysroot/bin/x86_64-unknown-re ## Policy Mapping +### Resilience / offline-first package sourcing + +Default Red Bear behavior is local-first: + +- use locally available package/source trees and overlay state for normal builds, +- treat upstream refresh as an explicit operator action only (`--upstream`, dedicated fetch/sync), +- do not fail policy-level expectations just because upstream network access is temporarily broken. + +This is required so builds and recovery workflows remain operable during upstream outages or +connectivity failures. + ### Upstream sync Use `local/scripts/sync-upstream.sh` when the goal is to refresh the top-level upstream Redox base. diff --git a/local/docs/repo-governance.md b/local/docs/repo-governance.md index 87689fb6..6a6f07d1 100644 --- a/local/docs/repo-governance.md +++ b/local/docs/repo-governance.md @@ -50,6 +50,16 @@ Do not describe compile-only work as supported hardware or a working desktop pat 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`