universalisos/docs/CONTRIBUTING.md

Contributing to UniversalisOS

Thank you for your interest in contributing. This guide covers build prerequisites, code conventions, testing requirements, and the PR process.

Build Prerequisites

Kernel (C++, freestanding)

Architecture	Toolchain	QEMU Package
ARMv7	arm-none-eabi-gcc	qemu-system-arm
AArch64	aarch64-linux-gnu-gcc	qemu-system-aarch64
RISC-V	riscv64-linux-gnu-gcc	qemu-system-riscv64

Install on Debian/Ubuntu:

sudo apt install gcc-arm-none-eabi qemu-system-arm
sudo apt install gcc-aarch64-linux-gnu qemu-system-aarch64
sudo apt install gcc-riscv64-linux-gnu qemu-system-riscv64

Mycelium Toolchain (Rust)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Coverage & Package Tools (Python)

• Python 3.11 or later
• No external dependencies (stdlib only)

VS Code Extension (optional)

cd mycelium-tfw-extension
npm install

Code Style

Naming Conventions

• Prefix: Use uos_ for all new APIs. Do not use PikeOS prefixes (p4_, UOS_PART_, P4_).
• Constants: UOS_HV_* (hypervisor ABI), UOS_SC_* (system calls), PV_SVC_* (ARMv7 PV).
• Files: snake_case.cpp, snake_case.h.

Language Rules

• Freestanding C++: No exceptions (-fno-exceptions), no RTTI (-fno-rtti).
• No dynamic allocation: Static/compile-time only in the kernel.
• No standard library: The kernel is freestanding; use __aeabi_* helpers when needed.
• No comments unless the why is non-obvious (hidden constraint, subtle invariant, bug workaround).
• Compiler flags: -Wall -Wextra -ffreestanding -O2 -fno-tree-vectorize -g.

Header Guards

Use #pragma once or #ifndef UOS_<MODULE>_H / #define UOS_<MODULE>_H.

Testing Requirements

All tests must pass before submitting a PR.

Kernel Tests

cd kernel

# Build all three architectures
make ARCH=armv7 PLATFORM=qemu-arm-virt
make ARCH=aarch64 PLATFORM=qemu-aarch64-virt
make ARCH=riscv PLATFORM=polarfire

Each build must complete with zero errors and zero warnings.

Mycelium Tests

cd /path/to/mycelium
cargo test

Currently 86 tests passing.

uos-cover Tests

cd tools/uos-cover
python3 -m pytest test/

Currently 87 tests.

uos-pkg Tests

cd tools/uos-pkg
python3 -m pytest test/

Currently 116 tests.

Combined Python Tests

cd tools
python3 -m pytest uos-cover/test/ uos-pkg/test/

Currently 203+ tests.

Pull Request Process

1. Branch

git checkout -b feature/your-feature-name

Use prefixes: feature/, fix/, docs/, refactor/.

2. Make Changes

Follow the code style rules above. Keep changes focused — one logical change per PR.

3. Build and Test

# Build the kernel for at least one architecture
cd kernel
make ARCH=armv7 PLATFORM=qemu-arm-virt

# Run Python tool tests
cd ../tools
python3 -m pytest uos-cover/test/ uos-pkg/test/

# Boot-test in QEMU (verify UART output)
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -kernel ../kernel/build/armv7/qemu-arm-virt/universalisos.elf

4. Commit

Write clear commit messages:

module: short description

Detailed explanation of what changed and why.

5. Push and Open PR

git push -u origin feature/your-feature-name

Open a pull request against main. Include:

• What the change does
• Which architectures were tested
• Test results (build output, test counts)

Architecture Boundaries

When making changes, respect these boundaries:

Directory	Scope
kernel/src/arch/armv7/	ARMv7-specific (boot, exceptions, MMU, context switch)
kernel/src/arch/aarch64/	AArch64 EL2 hypervisor (self-contained)
kernel/src/arch/riscv/	RISC-V port (self-contained)
kernel/src/core/	Shared core (ARMv7 only; AArch64/RISC-V do not pull these)
kernel/src/platform/drivers/	Shared device drivers
tools/	Python toolchain (coverage, packaging)

Important: A change to shared headers may break other architectures. Build and test all three when touching shared code.

Verification Workflow

There is no linter or typechecker. Verification is:

1. make ARCH=armv7 PLATFORM=qemu-arm-virt — must compile clean
2. Boot in QEMU — must reach UART banner and complete demo sequence
3. Python tests — all must pass
4. If shared headers changed, verify AArch64 and RISC-V builds too

License

By contributing, you agree that your contributions will be licensed under the MIT License.