vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e91c0ca4b6447092d3874bc907753ced79ac6af0
RedBear-OS/CONTRIBUTING.md
T
vasilito 1528e04b09 docs: consolidate build-system docs + Tier 1 message fixes 
Phase 2 of the build-system assessment:

Tier 1 (user-facing message fixes):
- mk/podman.mk: 'mk/config.mk' -> '.config' (the actual config location)
- mk/prefix.mk: vague 're-run the build' -> specific 'make prefix' guidance
- mk/virtualbox.mk: 'RedBearOS directory' -> 'Red Bear OS VM directory'
- src/bin/repo.rs: '{:?}' -> '{:#}' anyhow chain format + 'repo: ' prefix

Tier 2 (doc consolidation):
- Archive BUILD-SYSTEM-IMPROVEMENTS.md to local/docs/archived/ (self-labeled
  'HISTORICAL POST-MORTEM', no longer current).
- Add local/docs/BUILD-SYSTEM-ASSESSMENT-2026-07-18.md (459-line
  comprehensive assessment: architecture, quality, robustness, gaps).
- docs/README.md: refresh status note (2026-05-01 -> 2026-07-18, v4.0 ->
  v6.0); fix 'as an full fork' grammar.
- docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md: add status header noting
  canonical/secondary split vs CONSOLE-TO-KDE-DESKTOP-PLAN.md; fix grammar.
- HARDWARE.md: remove nonexistent PROFILE-MATRIX.md reference; repoint to
  README.md and the canonical desktop plan.
- local/docs/LOCAL-FORK-SUPREMACY-POLICY.md: 'currently 0.1.0' -> 'currently
  branch 0.3.1; legacy release archive at sources/redbear-0.1.0/'.
- local/docs/GRUB-INTEGRATION-PLAN.md: 'make all CONFIG_NAME=redbear-grub'
  -> canonical './local/scripts/build-redbear.sh redbear-grub'.
- recipes/AGENTS.md, recipes/core/AGENTS.md: replace upstream-Redox-pattern
  content with proper redirects to root AGENTS.md reflecting the local
  fork / path-fork model actually used by Red Bear.
- CONTRIBUTING.md: full rewrite for local fork workflow (Gitea, single-repo
  rule, path-fork model, patch governance, build-redbear.sh as canonical
  entry point, no AI attribution policy).
- README.md: add BUILD-SYSTEM-ASSESSMENT-2026-07-18.md to Documentation list.

Verified: cargo check (0 errors), cargo test --lib (35/35 passed),
cargo clippy (0 new warnings vs baseline).
2026-07-18 16:32:19 +09:00

328 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<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](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/<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.
```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/<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`](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`](./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.
Reference in New Issue View Git Blame Copy Permalink