Contributing to Portix OS

​

Welcome Contributors!

​

Prerequisites

​

Getting Started

git clone https://github.com/YOUR-USERNAME/Portix-OS.git
cd Portix-OS

rustup toolchain install nightly
rustup default nightly
rustup component add rust-src --toolchain nightly
rustup component add llvm-tools-preview

python scripts/build.py --mode=raw --run

git checkout -b feat/your-feature-name

​

Code Standards

​

Rust Code

​

No Standard Library (no_std)

#![no_std]
#![no_main]

// Use core and alloc instead
use core::fmt::Write;
use alloc::vec::Vec;

​

Minimize unsafe

// ✅ Good: Minimal unsafe scope
pub fn read_port(port: u16) -> u8 {
    let value: u8;
    unsafe {
        core::arch::asm!("in al, dx", out("al") value, in("dx") port);
    }
    value
}

// ❌ Bad: Unnecessary unsafe
pub unsafe fn some_safe_function() {
    // ... safe code ...
}

// SAFETY: Reading from I/O port 0x60 is safe because we've
// initialized the keyboard controller and this is the data port.
let scancode = unsafe { read_port(0x60) };

​

Code Formatting

cargo fmt
cargo clippy

• Use 4 spaces for indentation
• Keep lines under 100 characters
• Use snake_case for functions and variables
• Use CamelCase for types and enums

​

Assembly Code

• Use Intel syntax
• Add comments explaining each section
• Keep code readable with proper spacing
• Document any magic numbers or hardware-specific values

; Good: Documented and clear
mov eax, 0x80000000    ; CPUID function 0x80000000 - Get highest extended function
cpuid

; Bad: No explanation
mov eax, 0x80000000
cpuid

​

Commit Message Guidelines

type(scope): brief description in lowercase

[optional body explaining the change]

[optional footer with breaking changes or issue references]

​

Commit Types

​

Commit Scope

• mem - Memory management
• drivers - Device drivers
• graphics - Graphics subsystem
• fs - Filesystem
• boot - Bootloader
• arch - Architecture-specific code
• ui - User interface
• console - Terminal/console

​

Examples

# Good commits
git commit -m "feat(fs): add directory creation support to fat32"
git commit -m "fix(idt): correct page fault error code decoding"
git commit -m "docs(architecture): add boot process diagram"
git commit -m "perf(allocator): optimize buddy coalescing loop"

# Bad commits
git commit -m "Fixed bug"                    # Too vague
git commit -m "Updated code"                 # Not descriptive
git commit -m "FEAT: NEW FEATURE"            # Wrong case

​

Commit Best Practices

1. One change per commit: Don’t mix unrelated changes
2. Keep commits atomic: Each commit should be a complete, working change
3. Write in imperative mood: “add feature” not “added feature”
4. Explain why, not what: The diff shows what changed, explain why

​

Pull Request Process

cargo fmt
cargo clippy
python scripts/build.py --mode=raw --run

git push origin feat/your-feature-name

​

PR Checklist

• Code follows project style guidelines
• All commits have meaningful messages
• No compiler warnings
• Boots successfully in QEMU and VirtualBox
• Documentation updated if needed
• No breaking changes (or clearly documented)
• Serial output shows no errors

​

Areas to Contribute

​

Code Review Guidelines

• Be constructive and respectful
• Focus on code quality and maintainability
• Check for:
  • Correctness and safety
  • Performance implications
  • Code clarity and documentation
  • Adherence to project standards

​

Architecture Guidelines

​

Module Organization

kernel/src/
├── arch/          # Architecture-specific (IDT, GDT, ISR)
├── console/       # Terminal and commands
├── drivers/       # Device drivers
│   ├── bus/       # PCI, ACPI
│   ├── input/     # Keyboard, mouse
│   └── storage/   # ATA, FAT32, VFS
├── graphics/      # Framebuffer, rendering
├── mem/           # Memory allocator
├── time/          # Timers
├── ui/            # User interface
└── util/          # Utilities

​

Adding New Drivers

1. Create module in appropriate drivers/ subdirectory
2. Implement initialization function
3. Call from main.rs during boot
4. Add documentation
5. Export necessary types in mod.rs

​

Adding Terminal Commands

1. Create new file in console/terminal/commands/
2. Implement command handler:
   pub fn cmd_mycommand(term: &mut Terminal, args: &[&str]) {
       // Implementation
   }
   
3. Register in commands/mod.rs
4. Add help text

​

Testing Requirements

• Manual testing: Boot in QEMU and VirtualBox
• Functionality: Verify feature works as expected
• Regression: Ensure existing features still work
• Edge cases: Test boundary conditions

• Check allocator statistics
• Test under low memory
• Verify no leaks

​

Documentation

• Add doc comments to public APIs:
  /// Reads a byte from the specified I/O port.
  ///
  /// # Safety
  /// The caller must ensure the port is valid and mapped.
  pub unsafe fn read_port(port: u16) -> u8 {
      // ...
  }
  
• Update README if adding major features
• Add architecture docs for complex subsystems
• Include examples in doc comments

​

Communication

• Questions: Open a GitHub issue with the question label
• Bugs: Open an issue with the bug label and reproduction steps
• Feature requests: Open an issue with the enhancement label
• Discussions: Use GitHub Discussions for broader topics

​

License

​

Recognition