From 80da7bdebdada02ab25dedb0e083ae518d7ee8dc Mon Sep 17 00:00:00 2001 From: Vasilito Date: Mon, 11 May 2026 10:10:45 +0100 Subject: [PATCH] docs: update project knowledge base Update AGENTS.md with current patch chain state, KWin integration status, and consolidated patch governance. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- AGENTS.md | 50 +++++++++++++++++++ local/AGENTS.md | 1 + .../qtbase/P0-fix-broken-include.patch | 7 --- ...0-remove-redox-linkat-unlinkat-stubs.patch | 25 ---------- .../qtbase/P1-qplatformopengl-guard.patch | 1 - .../P2-enable-network-and-tuiotouch.patch | 23 --------- 6 files changed, 51 insertions(+), 56 deletions(-) delete mode 100644 local/patches/qtbase/P0-fix-broken-include.patch delete mode 100644 local/patches/qtbase/P0-remove-redox-linkat-unlinkat-stubs.patch delete mode 100644 local/patches/qtbase/P1-qplatformopengl-guard.patch delete mode 100644 local/patches/qtbase/P2-enable-network-and-tuiotouch.patch diff --git a/AGENTS.md b/AGENTS.md index 7a157ee337..1d5a133e5b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,56 @@ human-initiated operations. Durable Red Bear state belongs in `local/patches/`, The current baseline is **Red Bear OS 0.1.0** (Redox snapshot at build-system commit `f55acba68`). All recipe sources are pinned and archived in `sources/redbear-0.1.0/`. +## NO SILENT UPSTREAM PULLS — OFFLINE-FIRST POLICY + +**Red Bear OS is offline-first by default. No script, build target, or tool may silently pull +from any upstream repository without explicit user instruction.** + +This policy exists because silent upstream pulls are the root cause of stale and orphaned patches. +When sources change underneath wired patches, those patches break. The only safe workflow is: +frozen sources → patches applied atomically → build. + +### Rules + +1. **`REPO_OFFLINE` defaults to `1`** (offline). Set `REPO_OFFLINE=0` to explicitly allow online + fetching for non-protected development recipes only. +2. **`REDBEAR_RELEASE`** unconditionally forces offline mode — no network access during release + builds, even with `REPO_OFFLINE=0`. +3. **Protected recipes** (kernel, relibc, base, bootloader, all Red Bear custom recipes) are + **always offline** — they use archived sources from `sources/redbear-/`. +4. **`GNU_CONFIG_GET`** (wget for `config.sub`) is gated by `COOKBOOK_OFFLINE` — no download + when offline. +5. **Manual scripts** (`fetch-firmware.sh`, `fetch-all-sources.sh`, `provision-release.sh`) + may pull from upstream but MUST be explicitly invoked by the user. They are never called by + `make all` or `make live`. +6. **Toolchain downloads** (`mk/prefix.mk`) are the only ungated network access — they download + the cross-compiler toolchain from `static.redox-os.org`. These are one-time prerequisites, + not per-recipe source fetches. + +### What Counts as a Silent Upstream Pull + +Any of the following that runs without the user explicitly requesting it: +- `git clone`, `git fetch`, `git pull` against any remote +- `wget` or `curl` downloading source code or build artifacts +- Any HTTP request to `gitlab.redox-os.org`, `github.com`, `static.redox-os.org`, or any other + upstream hosting service + +### What Does NOT Count + +- Toolchain setup (`make prefix`) — one-time cross-compiler download +- QEMU firmware for non-x86 targets (`mk/qemu.mk` ARM/Raspberry Pi U-Boot) — not used in + standard x86_64 builds +- `make fetch` — explicit user action, gated by `REDBEAR_RELEASE` + +### Enforcement + +- Violations are bugs. If you find a script or build target that silently pulls from upstream, + fix it immediately: add an offline gate, or move the fetch to a manual-only script. +- The cookbook tool (`src/cook/fetch.rs`) enforces offline mode for protected recipes regardless + of `COOKBOOK_OFFLINE`. +- `COOKBOOK_OFFLINE=true` is the default in the Rust cookbook config parser when the environment + variable is not set. + ## STRUCTURE ``` diff --git a/local/AGENTS.md b/local/AGENTS.md index 0bd4a94c54..a97e9d1fab 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -110,6 +110,7 @@ Red Bear OS sources are frozen at release 0.1.0. Sources are immutable and archi - **All recipe sources are pinned** with `rev = "..."` in `recipe.toml` - **Archives are stored** in `sources/redbear-0.1.0/` with a manifest and BLAKE3 checksums - **Builds are offline by default** — `REPO_OFFLINE=1 COOKBOOK_OFFLINE=true` +- **NO silent upstream pulls** — see `AGENTS.md` "NO SILENT UPSTREAM PULLS" section for the full policy. Any script or build target that silently pulls from upstream is a bug. - **New releases are provisioned explicitly** via `provision-release.sh`, never automatically - **Old releases are NEVER deleted** — each new release is added alongside existing ones diff --git a/local/patches/qtbase/P0-fix-broken-include.patch b/local/patches/qtbase/P0-fix-broken-include.patch deleted file mode 100644 index c3207c8a6c..0000000000 --- a/local/patches/qtbase/P0-fix-broken-include.patch +++ /dev/null @@ -1,7 +0,0 @@ ---- a/src/network/socket/qnativesocketengine_unix.cpp -+++ b/src/network/socket/qnativesocketengine_unix.cpp -@@ -1,4 +1,3 @@ --#include - // Copyright (C) 2021 The Qt Company Ltd. - // Copyright (C) 2016 Intel Corporation. - // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only diff --git a/local/patches/qtbase/P0-remove-redox-linkat-unlinkat-stubs.patch b/local/patches/qtbase/P0-remove-redox-linkat-unlinkat-stubs.patch deleted file mode 100644 index 4cc30754b9..0000000000 --- a/local/patches/qtbase/P0-remove-redox-linkat-unlinkat-stubs.patch +++ /dev/null @@ -1,25 +0,0 @@ ---- a/src/corelib/io/qfilesystemengine_unix.cpp -+++ b/src/corelib/io/qfilesystemengine_unix.cpp -@@ -27,21 +27,4 @@ - #include - #include - --#ifdef Q_OS_REDOX --// relibc does not provide unlinkat/linkat yet (POSIX.1-2008 *at functions). --// Provide inline stubs that work for AT_FDCWD only - sufficient for --// FreeDesktop trash operations in this file. --#include --static inline int unlinkat(int dirfd, const char *pathname, int flags) --{ -- if (dirfd != AT_FDCWD || flags != 0) { errno = ENOTSUP; return -1; } -- return unlink(pathname); --} --static inline int linkat(int olddirfd, const char *oldpath, int newdirfd, const char *newpath, int flags) --{ -- if (olddirfd != AT_FDCWD || newdirfd != AT_FDCWD || flags != 0) { errno = ENOTSUP; return -1; } -- return link(oldpath, newpath); --} --#endif -- - #include - diff --git a/local/patches/qtbase/P1-qplatformopengl-guard.patch b/local/patches/qtbase/P1-qplatformopengl-guard.patch deleted file mode 100644 index 6aa3cf1ebb..0000000000 --- a/local/patches/qtbase/P1-qplatformopengl-guard.patch +++ /dev/null @@ -1 +0,0 @@ -../../../../local/patches/qtbase/P1-qplatformopengl-guard.patch \ No newline at end of file diff --git a/local/patches/qtbase/P2-enable-network-and-tuiotouch.patch b/local/patches/qtbase/P2-enable-network-and-tuiotouch.patch deleted file mode 100644 index 4b76f902ba..0000000000 --- a/local/patches/qtbase/P2-enable-network-and-tuiotouch.patch +++ /dev/null @@ -1,23 +0,0 @@ -diff -ruwN source-old/src/CMakeLists.txt source/src/CMakeLists.txt ---- source-old/src/CMakeLists.txt 2024-12-02 05:39:06.000000000 +0000 -+++ source/src/CMakeLists.txt 2026-04-30 00:00:00.000000000 +0000 -@@ -54,7 +54,7 @@ - endif() - if (QT_FEATURE_network) -- # add_subdirectory(network) # disabled for Redox -+ add_subdirectory(network) - if (ANDROID) - add_subdirectory(network/android/jar) - endif() -diff -ruwN source-old/src/plugins/generic/CMakeLists.txt source/src/plugins/generic/CMakeLists.txt ---- source-old/src/plugins/generic/CMakeLists.txt 2024-12-02 05:39:06.000000000 +0000 -+++ source/src/plugins/generic/CMakeLists.txt 2026-04-30 00:00:00.000000000 +0000 -@@ -18,7 +18,7 @@ - add_subdirectory(tslib) - endif() - if(QT_FEATURE_tuiotouch) -- # add_subdirectory(tuiotouch) # disabled for Redox (needs Network) -+ add_subdirectory(tuiotouch) - endif() - if(QT_FEATURE_libinput) - add_subdirectory(libinput)