Contribute to Moongate

Contributions are welcome: bug reports, fixes, features, tests, documentation, and examples. This guide explains how to prepare a contribution for review.

Before you start

Search the existing issues and pull requests before starting. Every feature starts with an issue that describes it in detail, as CODE_CONVENTION.md §13.1 requires; the same goes for a change to public APIs, packet behavior or persistence formats. Bug fixes and documentation corrections can go directly into a pull request.

For a bug report, include the Moongate version or commit, operating system, reproduction steps, expected and actual behavior, and relevant logs. Include the client version for network issues. Remove credentials and personal data from anything you share. Feature requests should explain the use case and intended behavior, not just the proposed implementation.

Set up your checkout

You need Git and the .NET 10 SDK to build the solution. Package verification also requires Bash and access to nuget.org. For website work, use the Node version in website/.nvmrc; Node is not needed for the C# build.

Fork the repository on GitHub, then create a branch from the current develop:

git clone https://github.com/YOUR-USERNAME/moongate.git
cd moongate
git remote add upstream https://github.com/moongate-community/moongate.git
git fetch upstream
git switch -c feature/short-description upstream/develop

Use a descriptive branch name, such as fix/packet-length or docs/plugin-guide. For running a server, see the Docker guide, including the required Ultima Online client files and first-start configuration.

Follow the project conventions

Read CODE_CONVENTION.md and use the repository’s .editorconfig. They define C# style, namespaces, type placement, test organization, and public interface documentation.

Keep changes focused on one problem. Follow the surrounding code and avoid unrelated formatting or refactoring. Write documentation, public XML comments, commit messages, and pull request descriptions in English. Discuss breaking changes explicitly and explain their effect on library consumers and plugins.

Use Conventional Commits, for example:

fix(network): reject invalid packet lengths
feat(persistence): add a collection query option
docs(plugins): clarify bundle deployment

Verify your changes

Run these commands from the repository root to match the solution checks in CI:

dotnet restore Moongate.slnx
dotnet build Moongate.slnx -c Release --no-restore
dotnet test Moongate.slnx -c Release --no-build

For opt-in concurrent database load tests, see Stress-test PostgreSQL persistence.

Add or update tests for changed behavior. For bug fixes, include a regression test that demonstrates the failure. Follow the test layout in CODE_CONVENTION.md and keep assertions focused on observable behavior. Prose-only corrections do not need new C# tests.

CI also verifies NuGet packages, runnable README examples, and third-party notices:

bash scripts/verify-packages.sh
./scripts/third-party-notices.sh
git diff --exit-code -- THIRD-PARTY-NOTICES.md

See NuGet package verification for prerequisites and troubleshooting. If a dependency change updates the notices, review and include that update in your commit so the CI comparison is clean.

For documentation or website changes, run:

npm --prefix website ci
npm --prefix website test
npm --prefix website run build

The build checks local links, images, and heading fragments. Edit the original Markdown sources rather than generated website files. See Writing documentation for preview commands and page registration. Library README examples retain their nuget-smoke markers so package verification can compile and run them.

Submit a pull request

1. Commit your focused change and push the branch to your fork.
2. Open a pull request against moongate-community/moongate:develop.
3. Explain the problem, resulting behavior, relevant issue, and checks you ran. Call out compatibility changes and any checks you could not run.
4. Address review feedback and resolve CI failures before merge. Update the documentation when behavior or configuration changes.

Keep discussions respectful and focused on the change. Maintainers review and merge contributions; opening a pull request does not require publishing packages or creating a release.

The project’s license is available in LICENSE. Keep existing copyright and license notices intact; dependency attribution is recorded in THIRD-PARTY-NOTICES.md.