# Contributing to Red Bear OS > **Authority:** This file is a quick orientation for contributors. The canonical contributor > runbook lives in [`AGENTS.md`](./AGENTS.md) (root) and [`local/AGENTS.md`](./local/AGENTS.md) > (local fork model, branch/submodule policy, durability rules, operator runbook). When this > file and AGENTS.md disagree, AGENTS.md wins. Thank you for your interest in contributing to Red Bear OS. This document will get you from "fresh clone" to "first merged change" without tripping over the project's discipline rules. **Please read this document until the end.** --- ## Code of Conduct We follow the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct). ## License Contributions to Red Bear OS are governed by the [MIT License](https://en.wikipedia.org/wiki/MIT_License). Each repository has a `LICENSE` file with the exact terms. Review it before contributing. ## Contribution Terms When making a contribution you agree to the following terms: - I understand these changes in full and will be able to respond to review comments. - I have read the [Developer Certificate of Origin](https://developercertificate.org/) and certify my contribution under its conditions. ## AI Policy Contributions made with the assistance of LLMs and AI tools are welcome. We care about the **quality of the result**, not how it was produced. **No AI attribution in commit messages or code comments.** A commit message like `"feat: add MSR scheme"` is correct; `"feat: add MSR scheme (Co-Authored-By: Claude)"` is not. Commit content is what matters; authorship tags are noise. --- ## Project model — read this first Red Bear OS is a **full fork** of Redox OS. Treat it the way Ubuntu treats Debian: - Upstream Redox is the base platform. - Red Bear carries integration, packaging, validation, and a subsystem release fork on top. - Upstream-owned source trees (`recipes/*/source/`) are disposable — they are re-extracted from immutable archives or copied from local forks on every build. - **Durable Red Bear state** lives in `local/patches/`, `local/recipes/`, `local/docs/`, `local/sources//`, and tracked Red Bear configs. Only changes in these locations survive `make distclean`. If a change exists only inside `recipes/*/source/`, it is **not yet preserved** for long-term Red Bear maintenance. Mirror it to the right durable location in the same session. See `AGENTS.md` § "DURABILITY POLICY" for the mapping table. ### WIP rule for contributors If an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a **local project** until upstream promotes it to first-class status. For contributors: - Upstream WIP may still be useful as input/reference. - Fixes intended for Red Bear shipping should normally land in the Red Bear release fork (`local/sources//`) or as patches in `local/patches//`. - When upstream later catches up, Red Bear prefers upstream and retires the local patches that are no longer needed. --- ## Where the project lives Red Bear OS lives on a self-hosted Gitea instance. **No GitHub, GitLab, or Codeberg mirror is authoritative.** | Field | Value | |----------|---------------------------------------------------| | Host | `https://gitea.redbearos.org` | | User | `vasilito` | | Web UI | `https://gitea.redbearos.org/vasilito` | | Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS` | **Single-Repo Rule:** there is exactly **one** repository. All component sources (kernel, relibc, drivers, system utilities) live here as submodule branches or tracked trees in `local/sources/`. Do not create new repositories, new branches, or new submodules. See `local/AGENTS.md` § "BRANCH AND SUBMODULE POLICY". ### Communication - **Issues** — file at `https://gitea.redbearos.org/vasilito/RedBear-OS/issues`. Use the label filters (`critical`, `high-priority`, `easy`, `good first issue`, `help wanted`) to find work that matches your skill level. - **Chat** — upstream Redox has [Matrix](https://matrix.to/#/#redox-join:matrix.org) and [Discord](https://discord.gg/JfggvrHGDY) rooms. Red Bear contributors are welcome there, but issue tracking happens on Gitea, not in chat. - **Merge requests** — open MRs on Gitea against the `0.3.1` branch. Small MRs review faster than large ones; split big work into reviewable slices. --- ## Quick orientation for new contributors | You want to… | Read this | |---|---| | Build the project | `AGENTS.md` § "BUILD COMMANDS" — canonical entry point is `./local/scripts/build-redbear.sh` | | Add a new package | `recipes/AGENTS.md` + `AGENTS.md` § "STRUCTURE" + § "CONVENTIONS" | | Fix a kernel bug | Edit `local/sources/kernel/` directly (path-fork model — see `local/AGENTS.md`) | | Fix a relibc POSIX gap | Edit `local/sources/relibc/` directly; rebuild prefix with `touch relibc && make prefix` | | Modify an upstream package | Add a patch in `local/patches//`, wire it into the recipe's `patches = [...]` | | Add a custom Red Bear package | Create under `local/recipes//`, symlink `recipes//` → local path | | Bump an upstream version | `local/scripts/upgrade-forks.sh --to=` (see `local/docs/RELEASE-BUMP-WORKFLOW.md`) | | Sync in-house crate versions | `./local/scripts/sync-versions.sh --check` (Cat 0/1/2 categories) | | Validate your change | `make validate` runs `lint-config`, init-service validator, file-ownership validator | | Understand the build cache | `local/docs/BUILD-CACHE-PLAN.md` — BLAKE3 dep-hash cache, binary store restore | | Run a sanity check after fork edits | `git -C local/sources/ log --oneline -3` + `git -C local/sources/ status` | --- ## Build system The canonical build entry point is `./local/scripts/build-redbear.sh`. It handles `.config` parsing, prefix staleness detection, protected-recipe authorization, pre-cooking critical packages, and source fingerprint tracking. Direct `make` invocations bypass these gates. ```bash # First-time setup echo 'PODMAN_BUILD?=0' > .config # native build (no Podman container) # CRITICAL: .config MUST NOT contain REDBEAR_RELEASE=... in development mode. # Canonical build ./local/scripts/build-redbear.sh redbear-mini # text-only target (dev/CI) ./local/scripts/build-redbear.sh redbear-full # desktop-capable target ./local/scripts/build-redbear.sh redbear-grub # text-only + GRUB bootloader # With online fetch for non-protected development recipes ./local/scripts/build-redbear.sh --upstream redbear-mini # Local fork development (protected recipes) export REDBEAR_ALLOW_PROTECTED_FETCH=1 ./local/scripts/build-redbear.sh --upstream redbear-mini # Boot in QEMU make qemu make qemu QEMUFLAGS="-m 4G" ``` After editing a local fork (`relibc`, `kernel`, `base`), rebuild the prefix before any recipe build: ```bash touch relibc && make prefix # rebuild relibc in the cross-toolchain touch kernel && make prefix # rebuild kernel-related toolchain parts ``` `build-redbear.sh` auto-detects stale prefix and rebuilds before any recipe build. **A stale prefix is the #1 cause of "undefined reference" link errors** after fork changes. See `AGENTS.md` § "BUILD COMMANDS" and `docs/06-BUILD-SYSTEM-SETUP.md` for the full reference. --- ## Patch governance Red Bear patches are durable artifacts. **Never remove a patch to fix a build failure — rebase it.** Full rules in `local/docs/PATCH-GOVERNANCE.md`. Critical rules: - **Recipe.toml is git-tracked** — changes to it are durable. - **Source trees are disposable** — `repo clean`/`distclean` destroy them. - **All source-tree edits must be patches** in `local/patches//` OR direct commits to `local/sources//` (path-fork model). - **Patch chain ordering matters** — patches that define types must come before patches that use them; cumulative patches must maintain line-number context. - **Never remove BINS entries** to fix build failures — fix the source or use `EXISTING_BINS`. - **Validate patches** with `./target/release/repo validate-patches ` after any patch change. - **Orphan-patch governance** — every patch must correspond to work present in the matching fork source tree. `verify-patch-content.sh` enforces this on every build preflight. When an orphan is detected, apply the decision tree in `AGENTS.md` § "Orphan-Patch Supersession Decision Tree" (do NOT blindly reapply). --- ## Style guidelines ### Rust Follow the official Rust standards. Run `rustfmt` on your changes. Project settings live in `rustfmt.toml` (max_width=100, brace_style=SameLineWhere) and `clippy.toml` (cognitive-complexity-threshold=100, type-complexity-threshold=1000). **Hard rules** (see `AGENTS.md` § "ANTI-PATTERNS"): - **No `as any` / `@ts-ignore`** — use proper `Result` handling. - **No `unwrap()` / `expect()` in library/driver code** — pervasive anti-pattern in this repo (~14k instances of technical debt). Use `Result` and `?`. - **No type suppression** — no `#[allow(...)]` for code you wrote. - **No speculative fallbacks** — handle errors explicitly. ### TOML (recipes and configs) - Recipe format: `[source]` + `[build]` + optional `[package]`. - WIP recipes MUST start with `#TODO` describing what is missing. - Custom flags MUST be set AFTER `DYNAMIC_INIT` (it overwrites CFLAGS/LDFLAGS/CXXFLAGS). - Cross-compilation: disable test suites (`BUILD_TESTING=OFF`, `--disable-tests`). - Configs use `[package_groups.]` sections (underscore, not hyphen). ### Git For user-visible work, keep the root [`CHANGELOG.md`](CHANGELOG.md) current and update the README "Current Status" section with the latest highlights so repository visitors can immediately see what changed. When a commit changes the visible system surface, supported hardware, build flow, shipped configs, or key docs, add a short user-facing changelog note in the same change. Commit message style (lowercase prefix + colon + short summary): ``` feat: fix: docs: chore: refactor: ``` --- ## Development recommendations - **Build incrementally.** `repo cook ` builds a single recipe; `make r.` is the shorthand. Use `--force-rebuild` to bypass the content-hash cache when debugging. - **Log everything when debugging.** `your-command 2>&1 | tee file-name.log` — capture full output for later analysis. - **Test different QEMU settings** when something fails. Pop!_OS, Ubuntu, Debian, and Fedora are the recommended host distributions. - **Check for missing POSIX/Linux functionality in relibc** when a port fails to build or crashes at runtime. The fork lives at `local/sources/relibc/`. - **Comment out configuration while testing** rather than removing it — preserves the record of what you tried. (Production commits should not contain commented-out code.) - **Small MRs review faster.** If a big MR stalls, split it into reviewable slices that each leave the tree building cleanly. - **Verify your change.** `make validate` runs `lint-config`, init-service validator, and file-ownership validator. For Rust changes: `cargo check`, `cargo clippy --all-targets`, `cargo test --lib`. --- ## What to work on ### By skill level **Non-programmers**: - Build the current branch (`./local/scripts/build-redbear.sh redbear-mini` or `redbear-full`) and boot it in QEMU (`make qemu`) or on bare metal. Add a row to [`HARDWARE.md`](./HARDWARE.md) describing what worked and what didn't. - File bugs at the Gitea issue tracker (check for duplicates first). - Fix typos in configuration (`config/`, `recipes/*/recipe.toml`) and documentation. - Improve documentation under `docs/` or `local/docs/`. **Know other languages, not Rust**: - Write unit tests (minimal Rust knowledge required). - Port C/C++ programs to Redox via `recipes/` (treat upstream WIP `TODO`s as inputs, not as the durable Red Bear shipping source of truth). - Web development on the website (minimal JavaScript only, for performance). **Know Rust, not OS development**: - See [`easy`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Aeasy) issues. - See [`good first issue`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Agood%20first%20issue) issues. - See [`help wanted`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Ahelp%20wanted) issues. - Improve build tooling (`installer`, `repo` cookbook binary, `redbear-*` utilities). - Improve the [Ion shell](https://gitea.redbearos.org/vasilito/RedBear-OS) or other mid-level projects. - Port Rust programs (look for the `port` label). - Improve relibc POSIX/Linux compatibility. **Know Rust + systems/OS development**: - Read `AGENTS.md`, `local/AGENTS.md`, and the relevant subsystem plan under `local/docs/`. - Search for `TODO`, `FIXME`, `BUG`, `UNOPTIMIZED`, `REWRITEME`, `DOCME` and fix what you find. - Look for issues labeled `critical`, `help wanted`, `feature`, `enhancement`, `bug`, or `port`. - Improve internal libraries (`libredox`, `redox-scheme`, `redox-event`). - Improve device drivers (GPU, USB, Wi‑Fi, Bluetooth — all first-class subsystems). - Improve profiling and optimization in kernel, filesystem, or network stack. ### Current priorities (see README "Current Status" table) The most impactful contributions right now: 1. **Qt6 Wayland `null+8` crash** — the #1 blocker for the graphical desktop. See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. 2. **AMD/Intel GPU hardware validation** on bare metal. See `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md`. 3. **USB controller maturity**. See `local/docs/USB-IMPLEMENTATION-PLAN.md`. 4. **Wi‑Fi native control plane**. See `local/docs/WIFI-IMPLEMENTATION-PLAN.md`. 5. **cub AUR pipeline hardening**. See `local/docs/CUB-PACKAGE-MANAGER.md`. 6. **tlc VFS remote backends and archive support**. See `local/recipes/tui/tlc/README.md`. 7. **Package maintainers** for the growing recipe catalog. ### Labels | Label | Meaning | |---|---| | [`critical`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Acritical) | Blocks release or core functionality | | [`high-priority`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Ahigh-priority) | Important, near-term work | | [`medium-priority`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Amedium-priority) | Should get done | | [`low-priority`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Alow-priority) | Nice to have | | [`tracking issue`](https://gitea.redbearos.org/vasilito/RedBear-OS/issues?q=label%3Atracking%20issue) | Roadmap tracking | --- ## Other ways to contribute ### Design Logos, UI design, app icons, desktop backgrounds, and themes are all welcome. Submit via the main repository or open an issue with attached assets. ### Donations To donate to **upstream Redox OS** (the base platform), see [https://www.redox-os.org/donate/](https://www.redox-os.org/donate/). Red Bear OS itself does not accept donations — contribute code, testing, or documentation instead.