Contributing

Pull requests are always welcome. If you fix or improve anything, feel free to float a PR back upstream.

Getting started

Fork icey on GitHub
Create a feature branch (git checkout -b my-feature)
Build and run the tests to make sure everything passes before you start:

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build build --parallel $(nproc)
ctest --test-dir build --output-on-failure

Code style

The project uses clang-format with a custom config (.clang-format in the repo root). The highlights:

C++20, LLVM base style
4-space indent, no tabs
Allman braces for definitions, K&R for control flow
Pointer/reference left-aligned (int* p, not int *p)
No column limit; manual formatting is preserved
Constructor initialiser lists: comma-first, one per line

Format your changes before committing:

clang-format -i src/path/to/file.cpp

Repo-specific structure and design rules live in conventions.md. Read that alongside this page if you are adding modules, moving public headers, or changing runtime-facing behaviour.

Commit messages

Use conventional commits: feat:, fix:, refactor:, test:, docs:, chore:, etc. Keep the subject line short, lowercase, imperative mood.

fix: resolve null pointer in WebRTC peer connection
refactor: replace raw pointers with unique_ptr in http client

Tests

If your change touches runtime behaviour, add or update a test. Tests live in tests/ and module-local src/*/tests/ directories and are built when -DBUILD_TESTS=ON is set. Run them with:

ctest --test-dir build --output-on-failure

Documentation

The docs toolchain is pinned under docs/package.json and built through the top-level Makefile.

Use these commands:

make docs        # doxygen xml + Sourcey site
make docs-dev    # regenerate xml, then run Sourcey dev server
make docs-api-md # optional: refresh the docs/api markdown mirror
make docs-check  # refresh markdown mirror, build site, and run API overview QA
make docs-docker # same docs build inside the docs container

The split is deliberate:

docs/sourcey.config.ts tells Sourcey how to render the site
Doxygen generates XML under build/doxygen/xml
Sourcey reads that XML directly for the API Reference tab
docs/api/*.md is an optional markdown mirror generated by the pinned Moxygen commit in docs/package.json
make docs-api-md passes --source-root $(pwd) so file-level Doxygen grouping is reconstructed consistently
make docs-check also fails if any top-level module overview table regresses to blank description rows

The normal docs path is make docs. Use make docs-api-md only when you want the repo-local markdown mirror refreshed as well.

Release flow

Release prose stays manual in CHANGELOG.md and ROADMAP.md. The mechanical version sync does not.

make release VERSION=2.4.0
make release-check VERSION=2.4.0
git commit -am "release: prepare 2.4.0"
git tag 2.4.0
git push origin main 2.4.0
make release-pin VERSION=2.4.0

What each step does:

make release syncs VERSION, package recipe versions, Arch metadata, and the public FetchContent examples after you have already written the matching CHANGELOG.md section.
make release-check fails if VERSION, Conan, vcpkg, Arch metadata, docs examples, and the changelog heading drift apart.
The GitHub release workflow runs on plain semantic-version tags from main and fails if the pushed tag does not match VERSION.
make release-pin is the post-tag helper for package-manager archive hashes.

Use releasing.md for the package-specific flow, including Conan verification, vcpkg archive pinning, Arch / AUR publication, the Homebrew tap formulae, and the Debian / PPA source-package staging path.

Licence

By contributing you agree that your work will be licensed under the LGPL-2.1+ licence.