From 54de45d4615b5d455a0f44b396b136dd047bfba8 Mon Sep 17 00:00:00 2001 From: vasilito Date: Sun, 5 Jul 2026 22:50:33 +0300 Subject: [PATCH] docs/scripts: enforce single-repo policy and +rb build-metadata suffix - Update AGENTS.md single-repo rule to explicitly forbid creating any new Gitea repositories and to require deleting per-component repos. - Change version suffix policy from pre-release -rb to build-metadata +rb in AGENTS.md, sync-versions.sh, apply-rb-suffix.sh, verify-fork-versions.sh. - Update migration instructions to push to existing submodule/ branches inside RedBear-OS, not create new repos. - Update BUILD-SYSTEM-IMPROVEMENTS.md and SLEEP-IMPLEMENTATION-PLAN.md to reference submodule/* branches instead of defunct per-component repos. - Fix delete-per-component-repos.sh example to use a real historical repo. --- local/AGENTS.md | 63 ++++++++++++--------- local/docs/BUILD-SYSTEM-IMPROVEMENTS.md | 26 ++++----- local/docs/SLEEP-IMPLEMENTATION-PLAN.md | 9 ++- local/scripts/apply-rb-suffix.sh | 26 ++++----- local/scripts/delete-per-component-repos.sh | 2 +- local/scripts/sync-versions.sh | 15 +++-- local/scripts/verify-fork-versions.sh | 24 ++++---- 7 files changed, 88 insertions(+), 77 deletions(-) diff --git a/local/AGENTS.md b/local/AGENTS.md index 54dab0003b..32dec2faf4 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -81,7 +81,16 @@ inside `RedBear-OS` either as: OR - **Tracked trees under `local/sources//`** — full source snapshots committed directly to the `RedBear-OS` repo as ordinary - files, versioned by Red Bear commits (not by external git history). + files, versioned by Red Bear commits (not by external git history), + OR +- **Local recipes under `local/recipes///source/`** — + original Red Bear projects (tlc, redbear-*, cub, etc.) with no upstream + outside this repo. + +**WE DO NOT CREATE NEW REPOSITORIES.** If a component needs a Red Bear +fork and does not already have a `submodule/` branch, adding +one is an **operator-only** decision. Agents **MUST NOT** create new +branches or new repos on their own. Operators and agents **MUST NOT**: @@ -95,12 +104,14 @@ If a recipe's `[source]` section currently points at a separate repo URL (e.g. `https://gitea.redbearos.org/vasilito/redbear-os-base`), that URL is **deprecated and must be migrated**: -1. Create or reuse a branch inside `RedBear-OS` named - `submodule/` (e.g. `submodule/relibc`). -2. Push the component's source tree to that branch. +1. Push the component's source tree to the existing `submodule/` + branch inside `RedBear-OS`. +2. Update the submodule's local `.git/config` origin to + `https://gitea.redbearos.org/vasilito/RedBear-OS.git`. 3. Replace the recipe's `git = "..."` URL with the in-repo submodule - path, and add a `[submodule]` entry referencing the new branch. -4. Update `local/AGENTS.md` and any other references. + path, and ensure `.gitmodules` references `branch = submodule/`. +4. Delete the per-component repository on Gitea. +5. Update `local/AGENTS.md` and any other references. **Enforcement.** The cookbook's fetch/validation path treats any component source fetched from outside `RedBear-OS` as a misconfiguration. @@ -137,8 +148,8 @@ Agents **MUST NOT**: - `git checkout -b ` — no new branches, no exceptions. - `git push origin HEAD:refs/heads/` — no pushing new branches. - create a branch named after a version (e.g. `redoxfs-0.9.0-rb1`) — this is - a **policy violation**. The `-rbN` suffix lives in `Cargo.toml` version - fields, not in branch names. + a **policy violation**. Version metadata lives in `Cargo.toml` version + fields (as `+rbN` build metadata), not in branch names. - create a branch named `submodule/` unless the operator has explicitly decided to fork a new upstream component. @@ -234,31 +245,29 @@ The migration was performed with the helper scripts in `local/scripts/`: | `local/scripts/redirect-to-submodules.sh` | For each component, fetches the per-component Gitea repo's HEAD, pushes it as `submodule/` on `RedBear-OS`, and rewrites `.gitmodules` to point at the new branch. Idempotent. Empty source repos are skipped. | | `local/scripts/delete-per-component-repos.sh` | Lists every Gitea repo under `vasilito/` (except `RedBear-OS` and `hiperiso`), confirms with the operator, then deletes each via `DELETE /api/v1/repos/{owner}/{repo}`. | -**To re-run for a future component** (e.g. a new per-component repo that -someone accidentally creates): +**To re-run for a future component** (if a per-component repo was accidentally +created or inherited): -1. Verify the per-component repo is a Red Bear component, not unrelated. +1. Verify the component belongs in `RedBear-OS`. 2. `export REDBEAR_GITEA_TOKEN=...` (or set up `~/.netrc`). -3. Push the working-tree HEAD as a branch: +3. Push the working-tree HEAD to the correct `submodule/` branch: ```bash cd local/sources/ - git push https://${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git \ - HEAD:refs/heads/submodule/ + git remote set-url origin https://gitea.redbearos.org/vasilito/RedBear-OS.git + git push -u origin master:refs/heads/submodule/ ``` -4. Declare it in `.gitmodules` (copy an existing entry, change the name + branch). -5. `./local/scripts/delete-per-component-repos.sh` to remove the orphaned repo. +4. Delete the per-component repository on Gitea. +5. Verify with: + ```bash + # Should print only: hiperiso, RedBear-OS + curl -fsS -H "Authorization: token $REDBEAR_GITEA_TOKEN" \ + 'https://gitea.redbearos.org/api/v1/users/vasilito/repos?limit=200' \ + | jq -r '.[].name' | sort -**To verify the rule holds at any time:** - -```bash -# Should print only: hiperiso, RedBear-OS -curl -fsS 'https://gitea.redbearos.org/api/v1/users/vasilito/repos?limit=200' \ - | jq -r '.[].name' | sort - -# Should print zero matches (CHANGELOG.md historical entries are exempt) -grep -rn 'gitea.redbearos.org/vasilito/redbear-os-' . --include='*.md' \ - | grep -v 'CHANGELOG.md' -``` + # Should print zero matches (CHANGELOG.md historical entries are exempt) + grep -rn 'gitea.redbearos.org/vasilito/redbear-os-' . --include='*.md' \ + | grep -v 'CHANGELOG.md' + ``` ### Connection details diff --git a/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md b/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md index 363ecedc2d..15fc49f499 100644 --- a/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md +++ b/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md @@ -506,24 +506,20 @@ local-fork source tree. **Problem.** `local/sources/base/` is a nested git repo (the local-fork model) with `origin = https://gitlab.redox-os.org/redox-os/base.git`. -**Resolved 2026-07-01:** the Red Bear-specific per-component fork at -`vasilito/redbear-os-base` has been migrated to the `submodule/base` -branch inside the canonical `RedBear-OS` repo per the SINGLE-REPO RULE -(see `local/AGENTS.md`). The base component now lives only as the -`submodule/base` branch on `RedBear-OS`. A Red Bear developer who +**Resolved 2026-07-01:** the base component has been migrated to the +`submodule/base` branch inside the canonical `RedBear-OS` repo per the +SINGLE-REPO RULE (see `local/AGENTS.md`). The base component now lives only as +the `submodule/base` branch on `RedBear-OS`. A Red Bear developer who commits inside `local/sources/base/` and runs `git push origin master` -would push Red Bear fork commits **to upstream Redox**, where they -will be rejected (or worse, silently fail). +pushes to the `submodule/base` branch of `RedBear-OS`. -**Current behavior.** Most Red Bear base commits are made by the -`Red Bear OS ` author bot during automated syncs, which -push to a different fork URL configured out-of-band. The inner-repo -`origin` is therefore orphaned from normal operator workflows. +**Current behavior.** All 9 declared submodules now point to +`https://gitea.redbearos.org/vasilito/RedBear-OS.git` on their +`submodule/` branch. The per-component repo era is over. -**Proposal.** Set the inner `local/sources/base/` origin to Red Bear's gitea -URL via `local/scripts/sync-fork-remotes.sh` (new file). Same treatment for -`local/sources/{relibc,kernel,bootloader,installer,redoxfs,userutils}` if any -of them have the same issue. +**Proposal.** Keep `local/scripts/sync-fork-remotes.sh` (or equivalent +maintenance) so that no submodule's `origin` drifts back to upstream Redox +or to an old per-component repo URL. **Expected gain.** Eliminates a footgun. Operators can commit + push from inside the local fork and reach the right remote. diff --git a/local/docs/SLEEP-IMPLEMENTATION-PLAN.md b/local/docs/SLEEP-IMPLEMENTATION-PLAN.md index 3a249cb2ee..ce4fc15a2c 100644 --- a/local/docs/SLEEP-IMPLEMENTATION-PLAN.md +++ b/local/docs/SLEEP-IMPLEMENTATION-PLAN.md @@ -300,8 +300,7 @@ the `recovered/quirks` branch in the outer RedBear-OS repo): - `4191b8543` — base submodule pointer (acpid AML sequence) - `850124559` — kernel submodule pointer (s2idle kstop handler) -- **Red Bear OS inner** commits (historical — these repos have since been - merged as `submodule/base` and `submodule/kernel` branches inside the - canonical `RedBear-OS` repo per the SINGLE-REPO RULE): - - `redbear-os-base 5d2d114` — acpid: full Linux AML S-state sequence - - `redbear-os-kernel 75c7618` — kernel: s2idle / s3 kstop handler +- **Red Bear OS inner** commits (historical — now found on `submodule/base` + and `submodule/kernel` branches inside the canonical `RedBear-OS` repo): + - `submodule/base 5d2d114` — acpid: full Linux AML S-state sequence + - `submodule/kernel 75c7618` — kernel: s2idle / s3 kstop handler diff --git a/local/scripts/apply-rb-suffix.sh b/local/scripts/apply-rb-suffix.sh index edd9103309..ba5ed706dd 100755 --- a/local/scripts/apply-rb-suffix.sh +++ b/local/scripts/apply-rb-suffix.sh @@ -1,21 +1,21 @@ #!/usr/bin/env bash -# apply-rb-suffix.sh — Apply the -rb version suffix to all Cat 2 forks. +# apply-rb-suffix.sh — Apply the +rb version build-metadata suffix to all Cat 2 forks. # # This script is now a thin wrapper around sync-versions.sh Phase 2. # It exists for backward compatibility and focused Cat-2-only operation. # # Policy (local/AGENTS.md § "Version conventions"): # -# Every Cat 2 fork version MUST be `-rb` where: +# Every Cat 2 fork version MUST be `+rb` where: # = the upstream version the fork currently tracks # = the current Red Bear OS git branch (e.g. 0.2.5) # -# The `-rb` suffix is a Cargo pre-release identifier. Per SemVer, a -# pre-release version (e.g. 0.9.0-rb0.2.5) is NEVER substituted for the -# corresponding stable version (0.9.0). +# The `+rb` suffix is Cargo build metadata. It does NOT affect +# SemVer precedence and allows transitive crates.io deps requiring +# `^X.Y.Z` to resolve to the local fork via [patch.crates-io]. # # Usage: -# ./local/scripts/apply-rb-suffix.sh # Apply -rb to all +# ./local/scripts/apply-rb-suffix.sh # Apply +rb to all # ./local/scripts/apply-rb-suffix.sh --check # Verify only # ./local/scripts/apply-rb-suffix.sh --rollback # Revert to stable X.Y.Z # @@ -55,11 +55,11 @@ if [[ -z "$BRANCH_VERSION" ]]; then exit 1 fi -RB_SUFFIX="-rb${BRANCH_VERSION}" +RB_SUFFIX="+rb${BRANCH_VERSION}" -# ---- Rollback mode: strip all -rb suffixes ---- +# ---- Rollback mode: strip all +rb suffixes ---- if [[ $ROLLBACK -eq 1 ]]; then - echo "=== Rolling back Cat 2 forks to stable versions (stripping -rb*) ===" + echo "=== Rolling back Cat 2 forks to stable versions (stripping +rb*) ===" for fork_dir in local/sources/*/; do [ -d "$fork_dir" ] || continue fork_name=$(basename "$fork_dir") @@ -70,8 +70,8 @@ if [[ $ROLLBACK -eq 1 ]]; then fi current="$(grep -E '^version\s*=' "$f" | head -1 | sed 's/.*"\(.*\)".*/\1/' || true)" [[ -n "$current" ]] || continue - if [[ "$current" == *"-rb"* ]]; then - base="$(echo "$current" | sed -E 's/-rb([0-9]+(\.[0-9]+\.[0-9]+)?)$//')" + if [[ "$current" == *"+rb"* ]]; then + base="$(echo "$current" | sed -E 's/\+rb([0-9]+(\.[0-9]+\.[0-9]+)?)$//')" sed -i "s|^version = \"${current}\"|version = \"${base}\"|" "$f" echo " ROLLBACK: $fork_name $current → $base" fi @@ -113,7 +113,7 @@ for fork in "${CAT2_FORKS[@]}"; do current="$(grep -E '^version\s*=' "$f" | head -1 | sed 's/.*"\(.*\)".*/\1/' || true)" [[ -n "$current" ]] || { echo " SKIP ${fork}: empty version"; continue; } - base="$(echo "$current" | sed -E 's/(-rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//')" + base="$(echo "$current" | sed -E 's/(\+rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//')" target="${base}${RB_SUFFIX}" if [[ "$current" == "$target" ]]; then @@ -149,6 +149,6 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" if [ -x "$SCRIPT_DIR/verify-fork-versions.sh" ]; then if ! "$SCRIPT_DIR/verify-fork-versions.sh" 2>&1 | grep -q "^All Cat 2 forks pass"; then echo "WARNING: verify-fork-versions.sh found content mismatches." >&2 - echo " The -rb suffix is applied but some forks may not match upstream." >&2 + echo " The +rb suffix is applied but some forks may not match upstream." >&2 fi fi diff --git a/local/scripts/delete-per-component-repos.sh b/local/scripts/delete-per-component-repos.sh index 8a04f00fbd..367acdf3d8 100755 --- a/local/scripts/delete-per-component-repos.sh +++ b/local/scripts/delete-per-component-repos.sh @@ -10,7 +10,7 @@ # ./local/scripts/delete-per-component-repos.sh # interactive # ./local/scripts/delete-per-component-repos.sh --dry-run # list only # ./local/scripts/delete-per-component-repos.sh --yes # no prompts -# ./local/scripts/delete-per-component-repos.sh --only redbear-os-base,redox-drm +# ./local/scripts/delete-per-component-repos.sh --only redbear-os-base # ./local/scripts/delete-per-component-repos.sh -h # this help set -euo pipefail diff --git a/local/scripts/sync-versions.sh b/local/scripts/sync-versions.sh index 1a7427a383..4c4ef1e015 100755 --- a/local/scripts/sync-versions.sh +++ b/local/scripts/sync-versions.sh @@ -8,7 +8,10 @@ # version = "" (e.g. "0.2.5") # # Cat 2 — Upstream Redox forks (local/sources/*/): -# version = "-rb" (e.g. "0.9.0-rb0.2.5") +# version = "+rb" (e.g. "0.9.0+rb0.2.5") +# +# The `+rb` suffix is Cargo build metadata, not a pre-release identifier. +# Using `-rb` is a policy violation. # # When the branch changes (e.g. 0.2.5 → 0.2.6), running this script bumps # Cat 1 versions to the new branch version AND updates Cat 2 suffixes to @@ -47,7 +50,7 @@ if [[ -z "$TARGET_VERSION" ]]; then fi echo "Target version: $TARGET_VERSION (from branch '$BRANCH')" -echo "Cat 2 suffix: -rb$TARGET_VERSION" +echo "Cat 2 suffix: +rb$TARGET_VERSION" echo "" # ---- Exclusions ---- @@ -80,9 +83,9 @@ should_exclude() { } # ---- Helper: extract upstream base from a Cat 2 version ---- -# Strips any existing -rb suffix to get the upstream base version. +# Strips any existing +rb build-metadata suffix to get the upstream base version. strip_rb_suffix() { - echo "$1" | sed -E 's/(-rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//' + echo "$1" | sed -E 's/(\+rb[0-9]+(\.[0-9]+\.[0-9]+)?)+$//' } # ---- Phase 1: Cat 1 — In-house crates (local/recipes/*/source/) ---- @@ -149,7 +152,7 @@ CAT2_CHANGED=0 CAT2_CHECKED=0 CAT2_DRIFT=0 -RB_SUFFIX="-rb${TARGET_VERSION}" +RB_SUFFIX="+rb${TARGET_VERSION}" update_cat2_version() { local f="$1" @@ -163,7 +166,7 @@ update_cat2_version() { current="$(grep -E '^version\s*=' "$f" | head -1 | sed 's/.*"\(.*\)".*/\1/' || true)" [[ -n "$current" ]] || return 0 - # Strip any existing -rb suffix to get upstream base + # Strip any existing +rb build-metadata suffix to get upstream base base="$(strip_rb_suffix "$current")" target="${base}${RB_SUFFIX}" diff --git a/local/scripts/verify-fork-versions.sh b/local/scripts/verify-fork-versions.sh index 16dc0816e1..d4a8027d77 100755 --- a/local/scripts/verify-fork-versions.sh +++ b/local/scripts/verify-fork-versions.sh @@ -2,13 +2,17 @@ # verify-fork-versions.sh — Enforce the "no fake version label" rule. # # For each local Cat 2 fork under local/sources// that has a -# version field of the form `-rb`, verify that: +# version field of the form `+rb`, verify that: # 1. The fork's source content is a real rebase onto the matching # upstream `` release (with the Red Bear patches applied). # 2. The `` part matches the current Red Bear OS git branch. # 3. The `version` field in the fork's Cargo.toml starts with that # upstream release tag. # +# The `+rb` suffix is Cargo build metadata, NOT a pre-release identifier. +# Using `-rb` is a policy violation because Cargo treats it as a pre-release +# and transitive deps requiring `^X.Y.Z` will not resolve to the fork. +# # This script is invoked by build-preflight.sh and apply-rb-suffix.sh. # It returns exit code 1 if any fork fails the check. @@ -38,18 +42,18 @@ for fork_dir in local/sources/*/; do version=$(grep -E '^version\s*=' "$toml" | head -1 | sed -E 's/.*"([^"]+)".*/\1/') || true [ -n "$version" ] || continue - # Only check Cat 2 forks (those with -rb suffix) - if [[ "$version" != *"-rb"* ]]; then + # Only check Cat 2 forks (those with +rb build-metadata suffix) + if [[ "$version" != *"+rb"* ]]; then continue fi - # Extract the upstream base version (before -rb) and the branch version (after -rb) - base_version=$(echo "$version" | sed -E 's/-rb[0-9]+\.[0-9]+\.[0-9]+$//') || true - rb_branch=$(echo "$version" | sed -E 's/^.*-rb([0-9]+\.[0-9]+\.[0-9]+)$/\1/') || true + # Extract the upstream base version (before +rb) and the branch version (after +rb) + base_version=$(echo "$version" | sed -E 's/\+rb[0-9]+\.[0-9]+\.[0-9]+$//') || true + rb_branch=$(echo "$version" | sed -E 's/^.*\+rb([0-9]+\.[0-9]+\.[0-9]+)$/\1/') || true if [ -z "$base_version" ] || [ -z "$rb_branch" ]; then echo "ERROR: $toml has malformed version '$version'" >&2 - echo " Expected format: -rb (e.g. 0.9.0-rb0.2.5)" >&2 + echo " Expected format: +rb (e.g. 0.9.0+rb0.2.5)" >&2 violations=$((violations + 1)) continue fi @@ -79,10 +83,10 @@ for fork_dir in local/sources/*/; do continue fi - # Verify the -rb suffix matches the current branch + # Verify the +rb suffix matches the current branch if [ -n "$BRANCH_VERSION" ] && [ "$rb_branch" != "$BRANCH_VERSION" ]; then - echo "ERROR: $fork_name version suffix -rb$rb_branch does not match" >&2 - echo " current branch '$BRANCH' (expected -rb$BRANCH_VERSION)." >&2 + echo "ERROR: $fork_name version suffix +rb$rb_branch does not match" >&2 + echo " current branch '$BRANCH' (expected +rb$BRANCH_VERSION)." >&2 violations=$((violations + 1)) continue fi