Contributing

zuzu would love contributors!

Two contribution paths

zuzu is a microkernel, so contribution paths may look vastly different.

Userspace path (default)

• Preferred path for most contributions
• Covers daemons, protocol handling, service policy, shell/tools, and most iteration work
• Typical folders:
• user/
• include/zuzu/protocols/
• docs/

Kernelspace path (high bar)

• Kernel changes are expected to be rare and deliberate.
• Kernel architecture ports are exempt from this rule, but please reach out before starting a new port to discuss the design and scope.
• Typical folders:
• kernel/
• arch/
• core/

Kernelspace PRs should include a short justification explaining why this cannot remain a userspace policy change.

Project principles

• Keep the kernel minimal and policy-free where possible
• Prefer userspace policy and capability mediation over kernel special cases
• Keep changes understandable and easy to debug on QEMU

Prerequisites

• ARM embedded toolchain (arm-none-eabi-*)
• QEMU system emulator (qemu-system-arm)
• make

See README for platform-specific install commands.

Build and run

Build:

• make -j4

Run:

• make run

Debugging

Use the debug target and connect GDB as described in README.

Branch and commit guidance

• Keep commits as small as possible
• One logical change per commit
• Write clear commit messages

Preferred branch naming:

• userspace/
• kernel/

Commit message style:

• changetype(subsystem): short summary
• body explaining why and impact

Example:

• refactor(ipc): enforce endpoint handle validation in recv path

Code style guidance

• Match existing style in each file
• Keep functions short and single-purpose
• Prefer explicit error paths and return codes
• Avoid unrelated refactors in the same patch

Kernel and userspace boundaries

When in doubt:

• Kernel owns mechanisms (scheduling, memory, IPC primitives)
• Userspace owns policy (service naming, authorization, daemon behavior)

For security-sensitive service access:

• Prefer userspace mediation by trusted daemons
• Avoid hardcoding service policy in kernel paths

Decision rule:

• If it can be enforced in userspace with existing IPC/handle primitives, keep it in userspace.

Testing checklist

For userspace PRs

• Build succeeds: make -j4
• Boot still works in QEMU
• Changed daemon path is exercised manually
• No obvious regression in related userspace services

If your userspace change touches IPC, include at least:

• successful path test
• failure path test (bad handle, no permission, not found)

For kernelspace PRs

• All userspace checks above
• Boot + scheduler sanity after repeated runs
• Fault path coverage for changed logic (invalid handle/pointer/permission paths)
• One regression note listing subsystems at risk

If your kernel change touches one of these, include focused evidence:

• IPC dispatch/validation
• scheduler/context switching
• memory mapping and address-space transitions
• exception or IRQ entry paths

Documentation expectations

If behavior changes, update docs in the same PR:

• README when user-visible workflow changes
• docs files for architecture and protocol updates

Pull request checklist

• Problem statement and motivation
• Summary of approach
• Risks and limitations
• Test notes
• Follow-up items if intentionally deferred

Required extra fields for kernelspace PRs:

• Why userspace is insufficient
• Invariants preserved (what must remain true)
• Rollback plan if regression appears

Good first contribution ideas

• Improve diagnostics around syscall and IPC errors
• Add small targeted tests for userspace daemons
• Tighten docs around boot, IPC, and memory behavior
• Fix broken doc links and missing docs files

Not a good first contribution:

• Kernel scheduler, MMU, exception entry, or syscall ABI refactors

Naming convention

zuzu and zuzuOS will start to follow PascalCase for functions and types. Legacy code may use snake_case; when touching a subsystem, modernize its naming as part of that refactor.

Questions and design proposals

For larger changes:

• Write a short design note first
• Include alternatives considered
• Call out kernel/userspace boundary decisions

A suggested template is:

• context
• goals
• non-goals
• design
• migration plan
• risks