Contributing

​

Welcome Contributors!

• Code improvements and new features
• Bug fixes and security patches
• Documentation updates
• Test coverage improvements
• Performance optimizations

​

Contribution Workflow

# On GitHub, click "Fork" button
# Then clone your fork
git clone https://github.com/YOUR-USERNAME/aurora-os.git
cd aurora-os

git checkout -b feature/my-feature

git checkout -b feature/add-networking-stack

// Good: Clear function name and purpose
int allocate_physical_page(uint64_t* phys_addr) {
    // Implementation
}

// Bad: Unclear naming
int alloc(uint64_t* p) {
    // Implementation
}

/// Creates a new capability with the given permissions.
///
/// # Safety
/// The caller must ensure the object_id is valid.
pub unsafe fn create_capability(
    object_id: u64,
    perms: Permissions,
) -> Result<Capability, Error> {
    // Implementation
}

# Run all tests
make test

# Test QEMU boot
make run

# Run source validation
for f in tests/source-checks/*.sh; do bash "$f"; done

git commit -m "feat: add TCP/IP networking stack"

<type>: <description>

[optional body]

[optional footer]

git push origin feature/my-feature

​

Code Review Process

# Make changes based on feedback
git add .
git commit -m "refactor: address review feedback"
git push origin feature/my-feature

​

Branch Protection

​

Development Guidelines

​

Coding Standards

/**
 * Allocates a physical page frame.
 *
 * @param phys_addr Output pointer for physical address
 * @return 0 on success, -ENOMEM if no memory available
 */
int allocate_physical_page(uint64_t* phys_addr);

#![no_std]

/// Kernel capability system.
pub mod caps {
    /// A capability represents a reference to a kernel object
    /// with specific permissions.
    pub struct Capability {
        // ...
    }
}

# Context switch: switch from old to new task
# Args: %rdi = old_task, %rsi = new_task
.global context_switch
context_switch:
    # Save old task state
    push %rbp
    push %rbx
    # ... (implementation)

​

Security Considerations

• Memory safety checks
• Integer overflow protection
• Capability permission validation
• Input sanitization
• Proper error handling

// Bad: No overflow check
void* allocate(size_t count, size_t size) {
    return kmalloc(count * size);
}

// Good: Check for overflow
void* allocate(size_t count, size_t size) {
    if (count > SIZE_MAX / size) {
        return NULL;  // Overflow
    }
    return kmalloc(count * size);
}

​

Reporting Issues

​

Bug Reports

1. Description - Clear summary of the issue
2. Steps to Reproduce - Detailed reproduction steps
3. Expected Behavior - What should happen
4. Actual Behavior - What actually happens
5. Environment - OS, architecture, versions
6. Logs - Relevant error messages or logs

# Gather version information
uname -a
gcc --version
rustc --version

# Get build logs
make clean
make build 2>&1 | tee build.log

​

Feature Requests

1. Use Case - Why is this feature needed?
2. Proposed Solution - How should it work?
3. Alternatives - What alternatives exist?
4. Implementation Ideas - Any thoughts on implementation?

​

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Assume good intentions
• Help newcomers get started

​

Getting Help

​

License