Contributing

Contributing

Thanks for your interest in contributing to RealmEngine. This page covers the practical side — how to get set up, how branches and PRs work, and what's expected in terms of code quality.

---

Before You Start

• Check open issues to see if something is already in progress
• For significant changes (new systems, architecture changes), open an issue first to discuss the approach before writing code
• For small fixes (typos, test gaps, bug corrections) — just open a PR directly

---

Branching Strategy

Branch	Purpose
main	Production-ready code. CI runs on push. Releases are tagged here.
development	Active integration branch. Feature branches merge here first.
feature/your-thing	One branch per feature or fix, branched from development

# Start new work
git checkout development
git pull
git checkout -b feature/my-improvement

---

Making Changes

Code Style

• C# 13 / .NET 10 — the repo targets net10.0 across all projects
• nullable enable and ImplicitUsings enable are set globally in Directory.Build.props
• Follow the existing patterns in the file you're modifying — consistency over personal preference
• Avoid adding abstractions or helpers that are only used once
• Don't add comments explaining what the code does — only add them when the why isn't obvious

Architecture Conventions

• Engine logic goes in RealmEngine.Core organized by feature slice under Features/
• New MediatR commands/queries follow the pattern: Command/Query record + Handler class in the same file, in the relevant Features/ subfolder
• Models and interfaces belong in RealmEngine.Shared if shared across projects, otherwise in the project that owns them
• Game content lives in the PostgreSQL content catalog; use RealmForge to add or modify entities
• No production UI code in the engine libraries — zero dependency on any UI framework in Core/Shared/Data

Tests

Every change should have corresponding tests. The project uses xUnit + FluentAssertions.

[Fact]
public void Character_Should_Level_Up_When_Gaining_Required_XP()
{
    // Arrange
    var character = new Character { Level = 1, Experience = 0 };

    // Act
    character.GainExperience(100);

    // Assert
    character.Level.Should().Be(2);
}

• Aim for 100% line coverage on new code (the CI uploads coverage to Codecov)
• Tests live in [Project].Tests/ mirroring the source structure
• Use FakeXxx stubs (see Infrastructure/FakeServices.cs in Client.Tests) rather than mocking frameworks
• Mark Avalonia headless tests with [AvaloniaFact]; add [Trait("Category", "UI")] only for tests requiring a real display

---

Submitting a PR

1. Push your branch and open a PR against development (not main)
2. CI will run automatically — all tests must pass
3. The PR will get a coverage comment from ReportGenerator showing changed-file coverage
4. Keep PRs focused — one logical change per PR makes review faster
5. Update docs/ if your change affects documented behavior

PR Checklist

• Tests added/updated for all changed logic
• Build passes (dotnet build Realm.Full.slnx)
• All tests pass (dotnet test Realm.Full.slnx --filter "Category!=UI")
• Documentation updated if applicable
• No new compiler warnings introduced

---

Running CI Checks Locally

# Full build
dotnet build Realm.Full.slnx --configuration Release

# Full test suite (matches CI)
dotnet test Realm.Full.slnx --filter "Category!=UI" `
  --configuration Release `
  --collect "XPlat Code Coverage" `
  --settings coverage.runsettings

---

Questions?

Open a discussion or file an issue — happy to help get you oriented.