yaze/docs/B1-contributing.md

Contributing

Guidelines for contributing to the YAZE project.

Development Setup

Prerequisites

• CMake 3.16+: Modern build system
• C++23 Compiler: GCC 13+, Clang 16+, MSVC 2022 17.8+
• Git: Version control with submodules

Quick Start

# Clone with submodules
git clone --recursive https://github.com/scawful/yaze.git
cd yaze

# Build with presets
cmake --preset dev
cmake --build --preset dev

# Run tests
ctest --preset stable

Code Style

C++ Standards

• C++23: Use modern language features
• Google C++ Style: Follow Google C++ style guide
• Naming: Use descriptive names, avoid abbreviations

File Organization

// Header guards
#pragma once

// Includes (system, third-party, local)
#include <vector>
#include "absl/status/status.h"
#include "app/core/asar_wrapper.h"

// Namespace usage
namespace yaze::app::editor {

class ExampleClass {
public:
    // Public interface
    absl::Status Initialize();
    
private:
    // Private implementation
    std::vector<uint8_t> data_;
};

}

Error Handling

// Use absl::Status for error handling
absl::Status LoadRom(const std::string& filename) {
    if (filename.empty()) {
        return absl::InvalidArgumentError("Filename cannot be empty");
    }
    
    // ... implementation
    
    return absl::OkStatus();
}

// Use absl::StatusOr for operations that return values
absl::StatusOr<std::vector<uint8_t>> ReadFile(const std::string& filename);

Testing Requirements

Test Categories

• Stable Tests: Fast, reliable, no external dependencies
• ROM-Dependent Tests: Require ROM files, skip in CI
• Experimental Tests: Complex, may be unstable

Writing Tests

// Stable test example
TEST(SnesTileTest, UnpackBppTile) {
    std::vector<uint8_t> tile_data = {0xAA, 0x55};
    auto result = UnpackBppTile(tile_data, 2);
    EXPECT_TRUE(result.ok());
    EXPECT_EQ(result->size(), 64);
}

// ROM-dependent test example
YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
    auto rom_data = TestRomManager::LoadTestRom();
    if (!rom_data.has_value()) {
        GTEST_SKIP() << "ROM file not available";
    }
    // ... test implementation
}

Test Execution

# Run stable tests (required)
ctest --label-regex "STABLE"

# Run experimental tests (optional)
ctest --label-regex "EXPERIMENTAL"

# Run specific test
ctest -R "AsarWrapperTest"

Pull Request Process

Before Submitting

1. Run tests: Ensure all stable tests pass
2. Check formatting: Use clang-format
3. Update documentation: Update relevant docs if needed
4. Test on multiple platforms: Verify cross-platform compatibility

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Stable tests pass
- [ ] Manual testing completed
- [ ] Cross-platform testing (if applicable)

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated

Development Workflow

Branch Strategy

• main: Stable, release-ready code
• feature/: New features and enhancements
• fix/: Bug fixes
• docs/: Documentation updates

Commit Messages

type(scope): brief description

Detailed explanation of changes, including:
- What was changed
- Why it was changed
- Any breaking changes

Fixes #issue_number

Types

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test additions/changes
• chore: Build/tooling changes

Architecture Guidelines

Component Design

• Single Responsibility: Each class should have one clear purpose
• Dependency Injection: Use dependency injection for testability
• Interface Segregation: Keep interfaces focused and minimal

Memory Management

• RAII: Use RAII for resource management
• Smart Pointers: Prefer unique_ptr and shared_ptr
• Avoid Raw Pointers: Use smart pointers or references

Performance

• Profile Before Optimizing: Measure before optimizing
• Use Modern C++: Leverage C++23 features for performance
• Avoid Premature Optimization: Focus on correctness first

Documentation

Code Documentation

• Doxygen Comments: Use Doxygen format for public APIs
• Inline Comments: Explain complex logic
• README Updates: Update relevant README files

API Documentation

/**
 * @brief Applies an assembly patch to ROM data
 * @param patch_path Path to the assembly patch file
 * @param rom_data ROM data to patch (modified in place)
 * @param include_paths Optional include paths for assembly
 * @return Result containing success status and extracted symbols
 * @throws std::invalid_argument if patch_path is empty
 */
absl::StatusOr<AsarPatchResult> ApplyPatch(
    const std::string& patch_path,
    std::vector<uint8_t>& rom_data,
    const std::vector<std::string>& include_paths = {});

Community Guidelines

Communication

• Be Respectful: Treat all contributors with respect
• Be Constructive: Provide helpful feedback
• Be Patient: Remember that everyone is learning

Getting Help

• GitHub Issues: Report bugs and request features
• Discussions: Ask questions and discuss ideas
• Discord: Oracle of Secrets Discord

Release Process

Version Numbering

• Semantic Versioning: MAJOR.MINOR.PATCH
• v0.3.0: Current stable release
• Pre-release: v0.4.0-alpha, v0.4.0-beta

Release Checklist

• All stable tests pass
• Documentation updated
• Changelog updated
• Cross-platform builds verified
• Release notes prepared