RedBear-OS/CONTRIBUTING.md

Contributing to Red Bear OS

Authority: This file is a quick orientation for contributors. The canonical contributor runbook lives in AGENTS.md (root) and 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.

License

Contributions to Red Bear OS are governed by the 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 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/<component>/, 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/<component>/) or as patches in local/patches/<component>/.
• 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 and Discord 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/<component>/, wire it into the recipe's patches = [...]
Add a custom Red Bear package	Create under local/recipes/<category>/, symlink recipes/<category>/<name> → local path
Bump an upstream version	local/scripts/upgrade-forks.sh --to=<tag> (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/<component> log --oneline -3 + git -C local/sources/<component> 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.

# 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:

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/<component>/ OR direct commits to local/sources/<component>/ (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 <recipe> 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<T, E> 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.<name>] sections (underscore, not hyphen).

Git

For user-visible work, keep the root 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: <what changed>
fix: <what was broken>
docs: <what was documented>
chore: <housekeeping>
refactor: <what was restructured>

---

Development recommendations

• Build incrementally. repo cook <recipe> builds a single recipe; make r.<recipe> 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 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 TODOs 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 issues.
• See good first issue issues.
• See help wanted issues.
• Improve build tooling (installer, repo cookbook binary, redbear-* utilities).
• Improve the Ion shell 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	Blocks release or core functionality
high-priority	Important, near-term work
medium-priority	Should get done
low-priority	Nice to have
tracking issue	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/. Red Bear OS itself does not accept donations — contribute code, testing, or documentation instead.