Contributing

Contributing

How to get a change into NyxOS: the workflow, the coding standards, the verification expectations, and the documentation-sync rule.

This page mirrors CONTRIBUTING.md in the repository root, which is authoritative. Where they disagree, the file wins.

See also: Building, Debugging, Wiki-Conventions, Troubleshooting

Before you start

Open an issue or a discussion first for anything touching a core subsystem — paging, scheduling, syscalls, the VFS. Small bug fixes need no prior discussion.

Workflow

1. Fork and clone.
2. Verify a clean build before changing anything, so you know the baseline is good.
3. Branch, change, verify, commit.
4. Rebase onto the latest master.
5. Open a focused pull request — one feature or fix.

CODE — Verify the baseline

host $ make -C kernel clean && make -C kernel
host $ ./run.ps1

The build must finish with zero errors and zero warnings. AGENTS.md tracks the warning count across releases; a regression is a blocker, not a nit.

Coding standards

C

Rule	Detail
Braces	K&R — opening brace on the same line
Indent	4 spaces, never tabs
Naming	snake_case for functions and variables, UPPER_SNAKE for macros and constants
Typedefs	Struct and enum typedefs take the _t suffix
Visibility	Prefer static; file-internal symbols must be marked static
Comments	Only where the code is non-obvious — bit twiddling, hardware quirks, workarounds
Constants	No magic numbers; define a named constant
Library calls	memset_asm/memcpy, not libc. snprintf from kernel.h is the safe formatter
Allocation in interrupt context	Not unless every caller is audited and it is behind preempt_disable

CODE — House style

void func(int x) {
    if (x) {
        do_stuff();
    }
}

Assembly (NASM)

• Intel syntax, .asm extension
• Labels in snake_case, local labels prefixed with .
• ; comment blocks

CODE — House style

global load_page_directory
load_page_directory:
    mov cr3, rdi
    ret

Kernel-specific constraints

These are not style preferences; violating them produces bugs that are hard to find.

Constraint	Why
No floating point	The kernel is built -mno-sse -mno-mmx -mno-sse2
-mno-red-zone everywhere	Interrupts would clobber the 128 bytes below RSP
No large stack locals	The kernel stack is shared with the compositor's deep redraw chains; use kmalloc
SAVE_REGS first in an entry stub	Using a scratch register before it corrupts the interrupted context
Store higher-half aliases where required	Kernel stacks and LSTAR are unmapped at their low addresses under a user CR3
Spinlocks, not preempt_disable(), for cross-core state	preempt_disable stops a switch on the local core only
Network header fields in network byte order	Route everything through htons/htonl/ntohs/ntohl
GUI colours from theme.h roles	A literal fb_rgb(…) cannot be re-themed
GUI layout on the 1024×768 design grid	The compositor scales; deriving from fb_get_width() scales twice

The documentation-sync rule

AGENTS.md states it directly:

Every commit must keep these in sync: GitHub Wiki (nyx-os.wiki.git), website (docs/), README.md, and any version/status references in AGENTS.md.

Surface	Location
Wiki	nyx-os.wiki.git — this wiki
Website	docs/
Readme	README.md
Release log	The releases table in AGENTS.md

Important

A change that alters a constant, a syscall number, a default, or a capacity limit makes the wiki wrong until it is updated. Treat the documentation update as part of the change, not as follow-up work. See Wiki-Conventions.

Versioning

Every user-visible change gets a version bump and a row in the AGENTS.md releases table. Bump KERNEL_VERSION in kernel/core/kernel.h.

Development is deliberately incremental: most releases add exactly one capability and verify it. That is why the patch numbers run into the hundreds, and it is a feature — each release is small enough to bisect and to explain.

CODE — Commit message format

v5.x.y: Short description (72-char max)

Longer explanation of what changed and why, wrapped at 72 characters.
Include relevant bug numbers or context.

Verification

There is no test framework. Verification is manual, in QEMU, and the expectation is that you state what you ran.

Always

host $ make -C kernel clean && make -C kernel     # zero warnings
host $ ./run.ps1                                  # desktop loads

By subsystem

Touched	Run
Scheduler, timer, process lifecycle	mtdemo, then confirm the GUI stays stable
Memory, paging	cowtest, stacktest, vmtest, munmaptest, mprotecttest
SMP, locking	smpstress, smpthreads, tlbtest, and -Cpus 1 versus -Cpus 4
Syscalls	exec /init.elf — the regression suite
VFS, EXT2	Write to /mnt, reboot, read it back; verify the image with e2fsck
Networking	ping 127.0.0.1, tcploop, dhcp, tcpdrop
Cryptography	The matching *test command, and a live tls <host>
Images	deflatetest, pngtest, bmptest, giftest, jpegtest
Compositor	Open a Terminal, run several commands, drag/resize/snap windows, switch workspaces
Userspace programs	Run them, and pipe them

Tip

When you add a subsystem, add a self-test command for it. Known-answer tests against published vectors are how the crypto and image code is verified, and they make every later change cheap to check. See HOWTO-Add-a-shell-command.

Warning

Verify a filesystem writer against an external checker, not against itself. A driver that reads back what it wrote can be self-consistently wrong; that is why the EXT2 write path is checked with e2fsck.

Pull requests

1. One feature or fix per PR.
2. Rebased onto the latest master.
3. Zero warnings.
4. State what you tested and how.
5. Documentation surfaces updated.

Where to start

AGENTS.md ends with a "Next features to add" section listing the highest-priority work with its context and constraints. That is the maintained backlog.

Good entry points that touch little else:

• A new userspace coreutil — see HOWTO-Write-a-userspace-program
• A self-test command for an existing subsystem — see HOWTO-Add-a-shell-command
• A GUI application — see HOWTO-Add-a-GUI-application
• Wiki corrections — see Wiki-Conventions

Security issues

Do not open a public issue. Report privately:

• Discord: uselessalter
• Email: nyxos@inbox.lv

Expect acknowledgement within 48 hours. Crashes originating from untrusted input — network packets, malformed ELFs, filesystem images — are in scope even though NyxOS offers no security guarantee. Only the latest release on master receives fixes. See SECURITY.md and Security.

Contact

Open a discussion, ping uselessalter on Discord, or email nyxos@inbox.lv.

See also

• Source-Tree-Reference — where everything lives
• Building — toolchain, flags and the stale-build traps
• Debugging — how to diagnose what you broke
• Wiki-Conventions — documentation style
• Security — the threat model

External resources

• NyxOS repository — GitHub
• Issue tracker — GitHub