# Contributing to ModuOS

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

## Getting Started

### 1. Fork the Repository

```bash
# 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](Building-ModuOS.md) guide to set up your environment.

### 3. Create a Branch

```bash
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](https://github.com/NtinosTheGamer2324/ModuOS/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**:
```c
// 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**:
```c
int function_name(int arg1, int arg2) {
    if (condition) {
        // code
    } else {
        // code
    }
    
    for (int i = 0; i < 10; i++) {
        // code
    }
}
```

### Comments

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

**Function comments**:
```c
/**
 * 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**:
```c
// Explain WHY, not WHAT
// Good: Disable interrupts to prevent race condition
// Bad:  Set interrupt flag to 0
cli();
```

### Assembly Style

**NASM syntax**:
```nasm
; 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

```bash
# 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**:
```bash
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

```bash
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:

```c
// 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](Coding-Standards.md) - Detailed style guide
- [Debugging Guide](Debugging-Guide.md) - How to debug
- [Project Structure](Project-Structure.md) - Code organization