maui-linux/CONTRIBUTING.md

Contributing to .NET MAUI Linux Platform

Thank you for your interest in contributing to the .NET MAUI Linux Platform! This project is developed and maintained by MarketAlly LLC under the leadership of David H. Friedel Jr.

This document provides guidelines and information for contributors.

Code of Conduct

This project follows the .NET Foundation Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

• .NET 9.0 SDK
• Linux development environment (Ubuntu 22.04+ recommended)
• Git

Setting Up the Development Environment

1. Fork and clone the repository:

git clone https://github.com/your-username/maui-linux.git
cd maui-linux

2. Install dependencies:

# Ubuntu/Debian
sudo apt-get install libx11-dev libxrandr-dev libxcursor-dev libxi-dev libgl1-mesa-dev

# Fedora
sudo dnf install libX11-devel libXrandr-devel libXcursor-devel libXi-devel mesa-libGL-devel

3. Build the project:

dotnet build

4. Run tests:

dotnet test

How to Contribute

Reporting Bugs

• Check if the bug has already been reported in Issues
• Use the bug report template
• Include reproduction steps, expected behavior, and actual behavior
• Include system information (distro, .NET version, desktop environment)

Suggesting Features

• Check existing feature requests first
• Use the feature request template
• Explain the use case and benefits

Pull Requests

1. Create a branch from main:

git checkout -b feature/your-feature-name

2. Make your changes following the coding guidelines

3. Add or update tests as needed

4. Ensure all tests pass:

dotnet test

5. Commit your changes:

git commit -m "Add feature: description"

6. Push and create a pull request

Coding Guidelines

Code Style

• Use C# 12 features where appropriate
• Follow .NET naming conventions
• Use var for obvious types
• Prefer expression-bodied members for simple methods
• Use nullable reference types

File Organization

Views/          # Skia-rendered view implementations
  Skia*.cs      # View classes (SkiaButton, SkiaLabel, etc.)

Handlers/       # MAUI handler implementations
  *Handler.cs   # Platform handlers

Services/       # Platform services
  *Service.cs   # Service implementations

Rendering/      # Rendering infrastructure
  *.cs          # Rendering helpers and caches

tests/          # Unit tests
  Views/        # View tests
  Services/     # Service tests

Naming Conventions

• Views: Skia{ControlName} (e.g., SkiaButton, SkiaCarouselView)
• Handlers: {ControlName}Handler (e.g., ButtonHandler)
• Services: {Feature}Service (e.g., ClipboardService)
• Tests: {ClassName}Tests (e.g., SkiaButtonTests)

Documentation

• Add XML documentation to public APIs
• Update README and docs for new features
• Include code examples where helpful

Example:

/// <summary>
/// A horizontally scrolling carousel view with snap-to-item behavior.
/// </summary>
public class SkiaCarouselView : SkiaLayoutView
{
    /// <summary>
    /// Gets or sets the current position (0-based index).
    /// </summary>
    public int Position { get; set; }
}

Testing

• Write unit tests for new functionality
• Maintain test coverage above 80%
• Use descriptive test names: MethodName_Condition_ExpectedResult

Example:

[Fact]
public void Position_WhenSetToValidValue_UpdatesPosition()
{
    var carousel = new SkiaCarouselView();
    carousel.AddItem(new SkiaLabel());

    carousel.Position = 0;

    Assert.Equal(0, carousel.Position);
}

Architecture Overview

Rendering Pipeline

1. LinuxApplication creates the main window
2. SkiaRenderingEngine manages the render loop
3. Views implement Draw(SKCanvas canvas) for rendering
4. DirtyRectManager optimizes partial redraws

View Hierarchy

SkiaView (base class)
├── SkiaLayoutView (containers)
│   ├── SkiaStackLayout
│   ├── SkiaScrollView
│   └── SkiaCarouselView
└── Control views
    ├── SkiaButton
    ├── SkiaLabel
    └── SkiaEntry

Handler Pattern

Handlers connect MAUI virtual views to platform-specific implementations:

public class ButtonHandler : ViewHandler<IButton, SkiaButton>
{
    public static void MapText(ButtonHandler handler, IButton button)
    {
        handler.PlatformView.Text = button.Text;
    }
}

Development Workflow

Branch Naming

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test additions/fixes

Commit Messages

Follow conventional commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• test: - Tests
• refactor: - Code refactoring
• chore: - Maintenance

Pull Request Checklist

• Code follows style guidelines
• Tests added/updated
• Documentation updated
• All tests pass
• No breaking changes (or documented if unavoidable)

Areas for Contribution

High Priority

• Additional control implementations
• Accessibility improvements (AT-SPI2)
• Performance optimizations
• Wayland support improvements

Good First Issues

Look for issues labeled good-first-issue for beginner-friendly tasks.

Documentation

• API documentation improvements
• Tutorials and guides
• Sample applications

Getting Help

• Open a Discussion for questions
• Join the .NET community on Discord
• Check existing issues and discussions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to .NET MAUI on Linux!