Contributing
Contributor guide
Build, test and improve the language and its documentation.
Kalandra's compiler and runtime are written in C++23; the website uses SvelteKit and user documentation uses Tiramisu. Contributions can improve language behavior, diagnostics, portability, editor support, examples or documentation. Start with a reproducible issue and a focused change.
Build the native tools
Install CMake, Ninja and the pinned LLVM/MLIR/Clang dependencies described in the repository build guide. Metal builds need a supported Mac and the Apple Metal toolchain. Do not substitute arbitrary LLVM versions: the compiler integrates with version-specific MLIR APIs.
cmake --preset native
cmake --build --preset native
ctest --preset nativeFind the relevant code
The lexer, parser, semantic analysis, typed IR and CPU lowering live under native/lib with public compiler headers under native/include. CPU runtime code lives under native/runtime. GPU code and tests live under native/metal-source, native/metal, native/vulkan and native/cuda. Editor protocol code is in native/lsp, and the VS Code integration is in native/editor/vscode. Tests and fixtures are registered through native/CMakeLists.txt and the CMake files it includes. Benchmark runners are separate from correctness tests.
Read the implementation and relevant tests together. Preserve source locations, value and mutation rules, checked failures and task ownership. Compiler allocation strategies and ABI details are implementation concerns, not automatically language features.
Choose useful tests
Add a regression reproducer for a bug fix. For a language feature, cover accepted programs, rejected programs, result values and failure behavior. Use debug and optimized modes when lowering is affected. GPU changes need numerical checks on supported hardware; a successful host build alone does not verify GPU execution. Use the repository's sanitizer configurations for relevant ownership or concurrency changes.
Contribute documentation
Author public pages in apps/website/src/content/native as .tiramisu files. Use the tutorial for guided learning, the language reference for constructs, the library reference for callable built-ins, and HOWTO guides for specific tasks. Keep examples complete or name the companion files they require. Mark intentionally rejected examples explicitly. Write for a reader learning or using Kalandra. Explain behavior directly, name prerequisites, give expected results and link to detailed rules. Avoid branch status, internal progress reports or planning notes in user guides; use GitHub issues and pull requests for those. Keep historical changes in release notes.
When adding an example, update its expected result in tests/fixtures/docs-examples.json. New built-ins also need an entry in tests/fixtures/public-api.json and a full reference section. The coverage check compares that index with the compiler's callable built-ins. Run website checks and the documentation verifier; use --gpu only with a compiler built for the selected backend and compatible hardware.
bun install --frozen-lockfile
bun run check
bun run verify:docs --tools build/native/nativeThe default verifier executes CPU examples and reports GPU examples separately. To execute GPU examples too, provide a compatible GPU-enabled toolchain and pass --gpu with the matching --gpu-backend metal, vulkan or cuda. A build without that backend or a host without compatible hardware is not an execution check.
For UI overrides, use the documented local src/lib/components/index.ts barrel instead of editing installed Tiramisu packages. Keep page metadata, accessible navigation and code copying working.
Submit a focused change
Explain the user-visible problem and resulting behavior, include relevant test results, and disclose platform or hardware checks you could not run. Preserve attribution and dependency licenses. Report bugs with a minimal source example, commands, platform and tool versions; do not include credentials or private project data.