Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (91 loc) · 4.16 KB

CONTRIBUTING.md

File metadata and controls

123 lines (91 loc) · 4.16 KB
Raw

Contributing

Branching

  • main is the stable/integration branch.
  • Feature work happens on dedicated branches (e.g. Game, gui, gui-network) and is merged back via pull requests.

Commit messages

This project follows Conventional Commits:

<type>(<scope>): <short summary>

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. The scope is usually server, gui, or a sub-area (e.g. server/game, gui/audio, make, nix).

Following @commitlint/config-conventional, the header line must also respect:

  • type and scope are lowercase
  • the description doesn't start with an uppercase letter (no Sentence-case/Start-case/PascalCase/UPPER-CASE)
  • the description doesn't end with a .
  • the whole header is at most 100 characters

Examples from the repository's history:

fix(server/game): improve debug messages in GameLogic
feat(make): move to vcpkg to download gui's required packages
fix(gui/audio): use the system's miniaudio header file

Enforcement

A commit-msg git hook (.githooks/commit-msg) rejects commits whose first line doesn't match the rules above. Enable it once per clone:

make hooks

This runs git config core.hooksPath .githooks, so the hook applies to every commit you make in this repository going forward. Merge/Revert commits generated by git are exempted automatically.

Code style

  • C++20, formatted with clang-format. Run before committing:

    make format

  • Compiler warnings are treated strictly (-Wall -Wextra -Wpedantic plus a curated set of -Werror=... flags, see server/CMakeLists.txt and gui/CMakeLists.txt). New code must build warning-clean.

Adding a new server command

  1. Create server/src/Commands/<Name>.{hpp,cpp} (or server/src/Commands/Gui/<name>.{hpp,cpp} for GUI-facing commands) implementing ICommand.
  2. Implement the actual game-state mutation in game::GameLogic if needed.
  3. Register the command in Client::registerCommands() (server/src/Client.cpp), in _aiCommands or _guiCommands as appropriate.

Adding a new GUI scene

  1. Create gui/src/Scene/<Name>.hpp implementing IScene (onEnter, update, draw, onExit).
  2. Add a matching value to Zappy::SceneState (gui/src/IScene/IScene.hpp).
  3. Handle the transition in SceneManager::update.

Dependencies

Only add new third-party C++ dependencies to the GUI via vcpkg (gui/vcpkg.json) — see INSTALLATION.md. Do not vendor single-header libraries into gui/src/Utils/ or add ad-hoc file(DOWNLOAD ...) steps to CMake.

Tests

Every component has an automated suite — see TESTING.md for the full picture. Run them all with:

make tests_run

When you change behavior, add or update the matching test:

  • Server game logic → a Criterion case in server/tests/unit/ (link-time access to GameLogic, Player, Map, Team, ...). Keep Test(...) names unique.
  • Server protocol → a pytest case in server/tests/functional/, driving a real server with zappy_client.py.
  • AI → a pytest case in ai/tests/, using the async fakes in fakes.py (no real socket needed).
  • GUI → a Criterion case in gui/tests/: math helpers, or protocol parsing via a fake INetworkClient.

New tests must keep the suites green and add no compiler warnings.

Pull requests

  • Keep PRs scoped to one area (server, gui or ai) when possible.
  • Ensure make succeeds for zappy_server, zappy_gui and zappy_ai, and that make tests_run passes, before opening a PR.
  • Run make format to avoid noisy formatting diffs.