Contributing

Contributing

Commit convention

Conventional Commits are enforced in CI via scripts/ci/commit_checker.py.

Format:

<type>(<scope>)?: <subject>

Rules:

• allowed types: feat, fix, chore, docs, refactor, perf, ci, build, style, revert, test
• subject max length: 72 chars

Local developer setup

./scripts/setup-dev.sh

This script creates .venv-pre-commit and installs the commit-msg hook.

Formatting

• Style file: .clang-format
• Local commands:

./scripts/format.sh
./scripts/format-check.sh

CMake shortcuts (top-level build only):

cmake --build build --target format
cmake --build build --target format-check

CI currently installs clang-format-19 in .github/workflows/clang-format.yml.

Test workflow

Compiler functional scripts

bash test/scripts/macos_compile.sh
bash test/scripts/linux_compile.sh

Python smoke/integration scripts

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install git+https://github.com/CoreTrace/coretrace-testkit.git
python test/examples/test_smoke.py
python test/examples/test_help_smoke.py
python test/examples/test_extern_project.py

Docker Linux validation

docker build -f test/docker/Dockerfile .

CI workflows

• build.yml
  • push branches: main, feat/*, feature/*
  • pull requests targeting main
  • builds on Linux and macOS
• clang-format.yml
  • formatting check
• commit-check.yml
  • commit message convention check on push

Development notes

• Prefer small, focused changes.
• Keep user-facing flags documented in CLI Reference.
• When changing runtime hooks, update both Instrumentation and Runtime Library.