Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
183 lines (131 loc) · 6.51 KB

CONTRIBUTING.md

File metadata and controls

183 lines (131 loc) · 6.51 KB

Contributing guidelines

Whether you're reporting issues or coding, follow the guidelines below to help keep the project consistent and maintainable.

All contributions, including issues, discussions, code comments, commit messages, and documentation, must be written in English. This ensures clarity and consistency for all contributors.

There are many ways to contribute, like:

Issues

Before opening a new issue:

  1. Make sure you're running the latest development version.
  2. Check if the issue already exists.

When filing an issue, include as much detail as possible, this helps reproducing and fixing the problem effectively:

  • Clear description of the bug.
  • Steps to reproduce.
  • Log file (qconsole.log) and crash output if applicable:
    • Attach the relevant log file.
    • For crashes, paste the console output that includes the backtrace.
  • Operating System and version. Example: Debian 13.
  • Full game version. Example: 0.70.0-alpha+0.0b1a20dcf win_msvc64-x86_64-debug. The version is obtained at the start of the log file, or by executing the version command in console.

Usage of generative AI / Large language models

Policy

This project requires that all contributions be human-authored.

Do not submit any code, documentation, issues, pull requests, commit messages or comments that are generated using AI or similar assistive tools (such as Microsoft Copilot, Anthropic Claude, ChatGPT...).

  • No AI-derived patches. If the change was proposed by an AI, it must not be ported over "by hand". If the idea came from AI, treat is as untrusted and do your own independent implementation.
  • No AI-assisted refactors. Mass rewrites, LLM-based formatting, or modernization are not accepted.
  • Enforcement. Maintainers may request clarification. PRs suspected of AI involvement may be rejected or reverted, and may lead to a ban.

Acceptable uses

  • Non-generative tools are allowed: static analyzers, formatters, linters, sanitizers, fuzzers and IDE features are fine as long they do not generate code.
  • Translation tools to help communicating between people.

Reasoning

This policy exists due to:

  • Copyright and licensing risk. The origin of the outputs may be unclear as these tools plagiarize the original sources without permission.
  • Security and authenticity. AI produces plausible code but may often look wrong. This could work, but would turn into undefined behavior, vulnerabilities, or time spent in a debugger.
  • Maintability. Changes must be explainable and reviewable. Humans can explain tradeoffs they consciously accepted. Generated code can't. If you can't explain why a specific line exists, it shouldn't be proposed at all.
  • Respect for maintainers. Submitting contributions generated by these tools waste maintainers resources to review them.

Responsibility

When submitting, you agree that:

  • The submission complies with this policy. Changes must be able to be explained and justified during review.
  • The submission can be declined if it is suspected to use AI or is raising reviewability concerns.

Coding

Compatibility

All changes must stay retro-compatible with the original game:

  • Assets must be loaded correctly.
  • Changes related to networking must be compatible with existing MOHAA clients and servers, these changes must not cause an error/disconnect.
  • Scripts/mods must remain functional.
  • The singleplayer campaign must be fully playable.

Coding style & Guidelines

  • Match the existing code style in any files you modify.
  • Avoid personal tags or author comments (.e.g., // @Name: note). Git already tracks authorship.
  • Ensure the code builds successfully using CI.
  • Use camelCase notation for all variables, and PascalCase notation for functions. Even if some existing code doesn't.
  • Format code using clang-format.
    • In VSCode from the command palette: Format document

Event declaration

When declaring a new Event, use the following structure:

Event EV_YourEventName  // Pascal Case naming convention
(
    "name",             // Each parameter on a new line
    flags,
    "format specifiers...",
    "argument names...",
    "description"
);

Code annotations

When modifying existing code from the original game or adding new classes, annotate your changes using one of the following patterns:

Additions

// Added in OPM
//  Description

Changes

// Changed in OPM
//  Description

Fixes

// Fixed in OPM
//  Description

Removal

// Removed in OPM
//  Description

If referencing a specific game version, replace OPM with that version number. Example:

// Added in 2.11
//  Make sure to clean turret stuff up
//  when the player is deleted

Known versions are 1.00, 1.10, 1.11, 2.0, 2.1, 2.11, 2.15, 2.30, 2.40.

You can also group multiple related functions like this:

// Added in OPM
//====
void Function1();
void Function2();
void Function3();
//====

For new source files, include the annotation after the license notice.

Source files

  • Always put the license notice as the header of the file (template here).
  • Only #include what's necessary.
  • Each source file should contain related classes and functions.

Pull Requests

Pull Requests are the preferred way of submitting code changes.

Before you start

  1. Discuss major changes first: open an issue or discuss about it.
  2. Create a branch based on the main branch (you shouldn't commit directly on main)
  3. Keep PRs as small as possible and focused: One clear purpose per PR.

Submitting a PR

  • Target the correct branch (usually main).
  • Add a short and clear description of what you changed and why.
  • Reference matching issues (e.g. Fixes #123).
  • Make sure your code builds and passes tests.
  • Test locally to ensure your changes don't break functionality or compatibility.

Reviews

  • Maintainers may ask for tweaks or commit changes directly to your PR, that's normal.
  • Stay polite and technical.
  • Once approved, your changes will be merged.

Additional Notes

  • Contributions follow the same license as the project.
  • Keep things consistent with existing code and docs.
  • If you're unsure about anything, you can discuss it on Discord via this link.