MetalOS/CONTRIBUTING.md

Contributing to MetalOS

Thank you for your interest in contributing to MetalOS!

Philosophy

MetalOS has a unique philosophy:

1. Minimal by Design: Every line of code must justify its existence
2. Purpose-Built: The goal is to run QT6 Hello World, not to be a general-purpose OS
3. Creative Freedom: We're not bound by POSIX or traditional OS designs
4. Precise Drivers: Hardware driver code must be accurate and follow specs

What We Accept

Welcome Contributions ✅

• Bug fixes in existing code
• Documentation improvements
• Build system enhancements
• Code simplification (making things simpler is better than adding features)
• Hardware driver improvements (especially GPU)
• QT6 port work
• Performance optimizations

Think Twice Before Adding ❌

• New features that don't directly support QT6
• Additional hardware support beyond target (AMD64 + RX 6600)
• Complex abstractions
• POSIX compatibility layers
• Security features (this is a demo project)
• Multi-user support

Golden Rule: Ask yourself "Does this help run QT6 Hello World?" before adding anything.

Code Style

C Code

// 4 spaces, no tabs
// snake_case for functions and variables
// PascalCase for types
// UPPER_SNAKE_CASE for constants

#ifndef METALOS_PATH_FILE_H
#define METALOS_PATH_FILE_H

#include <stdint.h>

#define MAX_BUFFER_SIZE 1024

typedef struct {
    uint64_t address;
    uint64_t size;
} MemoryBlock;

// Functions: descriptive names, clear purpose
int allocate_memory(uint64_t size);
void free_memory(void* ptr);

#endif // METALOS_PATH_FILE_H

C++ Code (for applications)

// 4 spaces, no tabs
// camelCase for methods
// PascalCase for classes

class DisplayManager {
private:
    uint32_t width;
    uint32_t height;
    
public:
    DisplayManager(uint32_t w, uint32_t h);
    void render();
};

Assembly

; Intel syntax
; Clear comments explaining what's happening
; Descriptive labels

section .text
global _start

_start:
    ; Set up stack
    mov rsp, stack_top
    
    ; Call kernel main
    call kernel_main
    
    ; Halt if we return
    cli
    hlt

Submission Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Test thoroughly: At minimum, test in QEMU
5. Commit with clear messages: git commit -m "Add feature: description"
6. Push to your fork: git push origin feature/my-feature
7. Open a Pull Request

Pull Request Guidelines

Good PR Description

## What does this do?

Implements basic PCI device enumeration in the HAL.

## Why is this needed?

Required to detect and initialize the Radeon RX 6600 GPU.

## How was it tested?

- Tested in QEMU with emulated PCI devices
- Verified PCI device list output
- Confirmed GPU is detected correctly

## Related Issues

Closes #42

What We Look For

• Clear purpose: Why is this change needed?
• Minimal scope: Does it do one thing well?
• Testing: Has it been tested?
• Documentation: Are non-obvious parts explained?
• No regressions: Does existing functionality still work?

Testing

Minimum Testing

Every PR should be tested in QEMU:

mkdir build && cd build
cmake ..
cmake --build .
cmake --build . --target qemu

Or if you already have a build directory:

cd build
cmake --build . --target clean
cmake --build .
cmake --build . --target qemu

Verify:

• Code compiles without warnings
• System boots (if applicable)
• Changes work as expected
• No crashes or hangs

Hardware Testing (if applicable)

For GPU driver changes or hardware-specific code, testing on real hardware is highly recommended.

Documentation

If you change functionality, update relevant documentation:

• Code comments for complex logic
• README.md for user-facing changes
• docs/ARCHITECTURE.md for design changes
• docs/DEVELOPMENT.md for development workflow changes

Questions?

• Open a GitHub Discussion for general questions
• Comment on existing Issues for specific topics
• Tag maintainers in PRs if you need feedback

Code of Conduct

Be respectful, constructive, and helpful. This is a learning project - everyone is welcome regardless of experience level.

License

By contributing, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

---

Happy hacking! 🚀