Contributing

Contributing to ModuOS

We welcome contributions to ModuOS! This guide will help you get started.

Getting Started

1. Fork the Repository

# Fork on GitHub, then clone your fork
git clone https://github.com/NtinosTheGamer2324/ModuOS.git
cd ModuOS
git remote add upstream https://github.com/NtinosTheGamer2324/ModuOS.git

2. Set Up Development Environment

Follow the Building ModuOS guide to set up your environment.

3. Create a Branch

git checkout -b feature/my-new-feature
# or
git checkout -b fix/issue-123

Contribution Types

Bug Fixes

Found a bug? Please:

1. Check if it's already reported in Issues
2. If not, create a new issue with:
   • Description of the bug
   • Steps to reproduce
   • Expected vs actual behavior
   • Logs from com1.log if applicable

New Features

Want to add a feature?

1. Open an issue to discuss the feature first
2. Get feedback from maintainers
3. Implement the feature
4. Submit a pull request

Documentation

Improve documentation:

• Fix typos
• Add examples
• Clarify explanations
• Update outdated information

Code Cleanup

• Remove unused code
• Improve code formatting
• Add comments
• Refactor for clarity

Coding Standards

C Code Style

Naming:

// Functions: lowercase with underscores
void process_create(void);
int fs_mount_drive(int drive);

// Variables: lowercase with underscores
int process_count;
uint64_t page_table_addr;

// Constants/Macros: UPPER_CASE
#define MAX_PROCESSES 256
#define PAGE_SIZE 4096

// Types: suffix with _t
typedef struct process process_t;
typedef enum fs_type fs_type_t;

Indentation:

• Use 4 spaces (no tabs)
• K&R style braces

Example:

int function_name(int arg1, int arg2) {
    if (condition) {
        // code
    } else {
        // code
    }
    
    for (int i = 0; i < 10; i++) {
        // code
    }
}

Comments

File headers:

//
// filename.c
// Brief description of file purpose
//
// Author: Your Name
// Date: 2025-01-01
//

Function comments:

/**
 * Brief description
 * 
 * @param arg1 Description of argument 1
 * @param arg2 Description of argument 2
 * @return Description of return value
 */
int function_name(int arg1, int arg2);

Inline comments:

// Explain WHY, not WHAT
// Good: Disable interrupts to prevent race condition
// Bad:  Set interrupt flag to 0
cli();

Assembly Style

NASM syntax:

; Comments start with semicolon
global function_name

function_name:
    push rbp
    mov rbp, rsp
    ; Function body
    pop rbp
    ret

Pull Request Process

1. Make Your Changes

# Edit files
vim src/kernel/feature.c

# Build and test
docker run --rm -it -v "%cd%":/root/env modu-os make clean build-AMD64
run.bat

# Verify changes work

2. Commit Changes

Commit message format:

type: Brief description (50 chars max)

Longer explanation if needed (wrap at 72 chars).
Explain WHY the change was made, not just WHAT.

Fixes #123

Commit types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• refactor: Code refactoring
• test: Adding tests
• chore: Build/config changes

Example:

git add src/kernel/feature.c
git commit -m "feat: Add support for XYZ

Implements feature XYZ as discussed in issue #123.
This allows users to do ABC.

Fixes #123"

3. Push to Your Fork

git push origin feature/my-new-feature

4. Create Pull Request

1. Go to your fork on GitHub
2. Click "New Pull Request"
3. Select your branch
4. Fill in description:
   • What does this PR do?
   • Why is this change needed?
   • How was it tested?
   • Related issues?

5. Code Review

• Maintainers will review your code
• Address any feedback
• Push additional commits if needed
• Once approved, PR will be merged

Testing Guidelines

Manual Testing

Minimum tests:

1. Build succeeds without warnings
2. Kernel boots to shell
3. Feature works as intended
4. No regressions (existing features still work)

Test checklist:

[ ] Boots successfully
[ ] No kernel panics
[ ] New feature works
[ ] File operations work (dir, cat)
[ ] Memory test passes
[ ] Games still launch
[ ] No obvious memory leaks

Adding Test Cases

If adding complex features, document test cases:

// test_feature.c
void test_new_feature(void) {
    // Test case 1: Normal operation
    assert(feature(1, 2) == 3);
    
    // Test case 2: Edge case
    assert(feature(0, 0) == 0);
    
    // Test case 3: Error handling
    assert(feature(-1, 0) == ERROR);
}

Areas to Contribute

High Priority

• USB driver support: Finish UHCI/OHCI/EHCI implementations
• Networking: Add network stack and drivers
• File write support: Implement FAT32 write operations
• Multi-user support: User accounts and permissions

Medium Priority

• Additional file systems: ext2, ext3, NTFS read support
• Better memory management: Slab allocator, demand paging
• GUI framework: Basic windowing system
• More hardware support: SATA III, NVMe, modern graphics

Low Priority (Nice to Have)

• Optimization: Performance improvements
• Documentation: More examples and tutorials
• Testing: Automated test suite
• Cleanup: Code refactoring and organization

Communication

Where to Ask Questions

• GitHub Issues: Bug reports, feature requests
• GitHub Discussions: General questions, ideas
• Pull Request comments: Code-specific questions

Response Time

• Maintainers review PRs within 1-2 weeks
• Be patient! This is a hobby project

License

By contributing, you agree that your contributions will be licensed under the GNU General Public License v2.0.

Recognition

Contributors will be acknowledged in:

• README.md (Contributors section)
• Release notes
• Git commit history

Thank You!

Thank you for contributing to ModuOS! Every contribution, no matter how small, helps improve the project.

Next Steps

• Coding Standards - Detailed style guide
• Debugging Guide - How to debug
• Project Structure - Code organization