Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
302 lines (188 loc) · 7.88 KB

CONTRIBUTING.md

File metadata and controls

302 lines (188 loc) · 7.88 KB

Contributing to MonoGame Extended

Welcome to MonoGame.Extended! We're excited that you want to help expand the MonoGame ecosystem.

MonoGame.Extended is a community-driven extension library that adds practical utilities to MonoGame, including sprite batching helpers, input systems, collision detection, content pipeline extensions, and more.

As an extension library, we have different priorities and workflows than the core MonoGame framework. Please read this document fully before contributing.

Our Mission

MonoGame.Extended is guided by four principles:

Prototype to Production

Our tools help you prototype quickly and evolve into production without throwing away your work. We focus on solving present-day pain points rather than anticipating future needs.

Pragmatic, Not Opinionated

We are not an engine. We provide decoupled utilities that solve specific game development problems without dictating architecture.

Hardware Aware

Where appropriate, we leverage platform-specific capabilities rather than abstracting them away unnecessarily.

Expert Enabling

We aim to help developers grow by providing understandable, well documented implementations, not magic abstractions.Our goal is to save you time and share knowledge, not replace your expertise.

Branching & Workflow

MonoGame.Extended follows a GitFlow-style workflow:

  • main: stable branch for releases only
  • develop: active development branch
  • feature branches: created from develop
  • hotfix branches: created from main when necessary

All pull requests must target the develop branch unless explicitly instructed otherwise.

Keep changes focused and scoped to a single concern.

Quick Contribution Rules

These rules prevent 90$ of contribution issues:

  • ❗ NEVER submit code you did not personally write.
  • ❗ NEVER submit decompiled or reverse engineered code.
  • ❗ DO NOT submit style only changes.
  • ❗ DO NOT reorder type members.
  • ❗ DO NOT introduce breaking APIs without discussion.
  • ✅ DO follow the existing style of the file you are modifying.
  • ✅ DO include unit tests when adding or modifying functionality.
  • ✅ DO open an issue before implementing large features.
  • ✅ DO keep PRs focused and reasonably sized.

Intellectual Property & Decompilation

We strictly prohibit submitting:

  • Decompiled XNA assemblies
  • Decompiled MonoGame code
  • Decompiled third-party libraries
  • Any code you do not have explicit rights to contribute

It does not matter:

  • How much you modify it
  • Whether the original project is discontinued
  • Whether you believe it is "safe"

If you did not write the code or receive explicit permission, do not submit it.

Violations will result in immediate removal of the contribution and may result in loss of contributor privileges.

All accepted contributions are distributed under the MIT License.

Getting Started Locally

Setting up your development environment is straightforward:

Clone the repository

git clone https://github.com/MonoGame-Extended/MonoGame.Extended.git
cd MonoGame.Extended
dotnet MonoGame.Extended.sln restore
dotnet MonoGame.Extended.sln build
dotnet MonoGame.Extended.sln test

Prerequisites

  • .NET SDK 9.0 or later
  • The current stable release of MonoGame

If you are working on content pipeline extensions, test with real content and document any new processor parameters.

Ways to Contribute

Bug Reports

Before opening a bug report:

  1. Search existing issues.
  2. Provide clear reproduction steps.
  3. Include expected vs actual behavior
  4. Provide minimal reproduction code (text preferred over screenshots).

Well structure bug reports significantly improve resolution speed.

Feature Requests

Before implementing a feature:

  1. Open a feature request.
  2. Explain the problem being solved.
  3. Justify why it aligns with our utility focused philosophy.
  4. Wait for discussion and approval.

Features that duplicate core MonoGame functionality will not be accepted.

Documentation & Examples

High quality documentation is just as valuable as code.

You can contribute by:

  • Improving XML documentation
  • Adding usage examples
  • Writing tutorials
  • Clarifying migration steps

Code Quality & Standards

Consistency and maintainability matter.

Architecture

  • Follow existing MonoGame patterns.
  • Prefer composition over inheritance when appropriate.
  • Keep dependencies minimal and justified.
  • Avoid unnecessary breaking changes.
  • Provide deprecation paths when required.

Refer to `CODING_GUIDELINES for detailed conventions.

Performance

Game development demands performance awareness:

  • Minimize allocations in hot paths.
  • Use pooling where appropriate.
  • Prefer Span<T> and ReadOnlySpan<T> when beneficial.
  • Consider cache-friendly layouts.
  • Profile performance sensitive changes.

Document performance implications in your PR description when relevant.

Testing Requirements

All new functionality requires test coverage.

  • Cover happy paths and edge cases.
  • Validate error conditions.
  • Update affected tests.
  • Provide manual test instructions if automation is insufficient.

CI must pass before review.

Pull Request Process

Before submitting:

  • Fork the repository.
  • Create a branch from develop.
  • Use descriptive commit messages.
  • Keep commits focused.
  • Ensure tests pass locally.

When submitting:

  • Complete the PR template.
  • Link related issues (closes #123).
  • Keep scope limited to one concern.
  • Ensure GitHub Actions CI passes.

Incomplete PRs will not be reviewed.

Issue Labels & Triage

MonoGame.Extended uses a structured label taxonomy to keep issue tracking consistent and filtering useful.

Please see TRIAGE.md for full label definitions and triage guidelines.

When opening an issue, maintainers will apply appropriate Kind, scope: and optional labels.

Code Review Expectations

We aim to acknowledge PRs within 3-5 business days.

Review focuses on:

  • Code quality & maintainability
  • Performance implications
  • Test coverage
  • Documentation completeness
  • API stability
  • Architectural consistency

Address reviewer feedback in new commits (avoid force-pushing during review).

Reviews focus on the code, not the contributor.

Version Compatibility

We:

  • Target the current MonoGame stable baseline version
  • Follow semantic versioning
  • Use major versions for breaking changes
  • Avoid depending on unreleased MonoGame APIs
  • Minimize external dependencies

If your contribution requires a version bump, open an issue first.

Platform Considerations

MonoGame.Extended supports:

  • Windows
  • macOS
  • Linux
  • Mobile platforms

Use conditional compilation where necessary:

#if WINDOWS
// Windows-specific code
#elif LINUX
// Linux-specific code
#endif

Document platform-specific limitations clearly.

Getting Help

Recognition

Contributors are recognized in release notes and README acknowledgements. Significant contributors may be invited to join the maintainer team.

Licensing

MonoGame Extended is under the MIT License unless a portion of code is explicitly stated elsewhere. See LICENSE for more details. Third-party libraries used by MonoGame Extended are under their own licenses, we always seek permission from the original author of those libraries.. Please refer to those libraries for details on the license they use.

We accept contributions in "good faith" that it isn't bound to a conflicting license.

By submitting a PR you agree to distribute your work under the MonoGame.Extended license and copyright.

Thank you for helping make MonoGame.Extended better for the entire community.

💖 The MonoGame.Extended Team