# Contributing to Solarus

Thank you for your interest in contributing to Solarus! Please read this document before opening a merge request.

## Before you start

For anything beyond a trivial fix, **open an issue first** (or comment on an existing one) to discuss the intended change. This avoids wasted effort if the direction doesn't align with the maintainers' goals. Once there is agreement on the approach, you can proceed with the implementation.

## How to contribute

1. **Fork** the repository and create a branch from `dev`.
2. Use a descriptive branch name that reflects the work: `fix/crash-on-map-load`, `feature/new-movement-type`, `refactor/entity-cleanup`.
3. Make your changes following the guidelines below.
4. Open a **merge request** against the `dev` branch with a clear description of what it does and why.

Codeowners have full rights to request changes or reject any contribution without obligation to explain in detail.

## Contribution scope

Keep contributions **atomic and focused**: one logical change per merge request. Avoid bundling unrelated fixes, refactors, and features together. A well-scoped MR is easier to review, easier to revert, and more likely to be accepted.

Good size guidelines:
- A bug fix touches the minimal set of files needed to fix the issue.
- A new feature is self-contained and does not silently refactor surrounding code.
- A refactor does not change behavior and is separate from feature work.

## Building the project

Before submitting, make sure the project compiles and tests pass on your machine.

- [compilation.md](compilation.md) — general build instructions
- [compilation.MSYS2.md](compilation.MSYS2.md) — Windows build instructions (MSYS2/ucrt64)

## Code style

- Match the style of the surrounding code. The project uses C++17.
- No trailing whitespace, no unnecessary blank lines.
- Name things clearly; avoid abbreviations unless they are well-established in the codebase.
- Do not add comments that restate what the code already says. Comments should explain *why*, not *what*.

## Lua API changes

If your change adds or modifies the Lua API exposed to quest scripts:
- Update the relevant documentation in [doc/docs/lua-api/](doc/docs/lua-api/).
- Keep backward compatibility in mind — quest authors depend on API stability.

## Tests

If you fix a bug or add a new behavior, add or update a test in [tests/src/tests/](tests/src/tests/). See [AGENTS.md](AGENTS.md) for an overview of the testing setup.

## Platform testing

Solarus targets Windows, macOS, and Linux. If your change touches platform-sensitive code (audio, rendering, input, file I/O), please test on the affected platform(s) and mention your test environment in the MR description. If you cannot test on a specific platform, say so — reviewers will know what to verify.

## Changelog

For any user-visible change (new feature, behavior change, bug fix), add a short entry to `CHANGELOG.md` under the `Unreleased` section. Keep entries brief and written from the user's perspective.

## Commit messages

Write short, imperative commit messages (`Fix crash when loading map`, not `Fixed crash` or `Fixes #123`). Reference issue numbers in the MR description rather than every commit.

## Good first issues

New to the codebase? Look for issues tagged **good first issue** on the issue tracker — these are scoped to be approachable without deep knowledge of the engine internals.

## Licensing

By submitting a merge request, you agree that your contribution will be licensed under the same license as the project.
