Contributing

Contributions are welcome. This page covers the conventions and workflow used in the project.

Getting started

git clone --recursive https://github.com/pfrithiofsson/micro.git
cd micro
cmake -B build
cmake --build build

Project structure

Path Contents
include/micro/core/ Public headers — one class per file
src/ Implementation files
examples/ Self-contained example programs
external/ Vendored dependencies (SDL3)
docs/ MkDocs documentation source
tools/ Helper scripts (res2code.py, etc.)
cmake/ CMake helpers and version template

Code style

The project enforces style automatically via CI:

  • clang-format — formatting is non-negotiable; run it before committing: bash clang-format -i src/*.cpp include/micro/core/*.hpp
  • clang-tidy — static analysis warnings are treated as errors.

If the CI badges on the README are green your changes are formatted correctly.

Conventions

  • C++20 throughout. Use concepts, ranges, and structured bindings freely.
  • No raw owning pointers. Use shared_resource / std::unique_ptr / std::shared_ptr.
  • Exceptions for errors. Throw micro::error (wraps SDL error messages) on failure.
  • Doxygen comments on every public symbol — @brief, @param, @throws, @code example.
  • Headers are #pragma once. No .cpp-visible implementation details in public headers.
  • Prefer [[nodiscard]] on functions that return a value callers should not ignore.

Adding a new feature

  1. Add the declaration to the appropriate header in include/micro/core/, with full Doxygen comments and a @code example.
  2. Add the implementation to src/.
  3. If the feature is user-facing, add or update the corresponding page in docs/api/.
  4. Add an example to examples/ if it benefits from a runnable demonstration.
  5. Verify the build and run clang-format/tidy.

Commit messages

The project follows Conventional Commits with the following prefixes:

  • FEAT: — New feature or capability
  • REFACTOR: — Code restructuring without changing behavior
  • FIX: — Bug fix
  • DOCS: — Documentation changes
  • EXAMPLE: — Changes to example programs
  • TOOLS: — Changes to build scripts or tooling

Format:

PREFIX: Brief description in sentence case

Optional longer explanation if needed.

Examples:

FEAT: Add text alignment options to renderer

REFACTOR: Move font drawing to renderer class

FIX: Correct alpha blending for semi-transparent textures

DOCS: Update quickstart with logical resolution example

Pull requests

  • Keep PRs focused — one feature or fix per PR.
  • Match the existing code style and documentation quality.
  • All CI checks must pass before review.

License

By contributing you agree that your changes will be licensed under the same zlib/libpng license as the rest of the project.