docs · project

Contributing#

Hekma is an open-source Rust workspace on GitHub. To contribute, build it with Rust 1.96.1, run cargo fmt, clippy and cargo test --workspace before you open a pull request, and accept the Contributor License Agreement. This page covers those steps, issues, what reviewers expect, and how to change these docs.

Build from source#

You need Rust 1.96.1 or newer. The repository pins 1.96.1 in rust-toolchain.toml, so with rustup a plain cargo picks it up.

git clone https://github.com/Ktesio/hekma.git
cd hekma
cargo build

The first build compiles a bundled SQLite and takes a few minutes. The binaries land in target/debug/ as hekma and hkm. To install your build, run cargo install --path crates/hekma (the repository root is a workspace, so cargo install --path . does not work).

When you try your build, use a throwaway state directory so you do not touch your real agents:

export HEKMA_STATE_DIR=$(mktemp -d) HEKMA_NO_UPDATE_CHECK=1
./target/debug/hekma agent list

Run the checks#

Run these before you open a pull request. CI runs the same checks on every pull request, with the tests on macOS, Linux and Windows:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets

cargo test --workspace runs everything, including tests that start real processes; it takes several minutes. CI also lints and tests with the latest stable Rust, which occasionally flags something 1.96.1 does not; reproduce it with cargo +stable clippy --workspace --all-targets -- -D warnings. The repository's testing guide explains the suites, the opt-in tests against real agents, and the performance benchmark.

For changes to CLI behaviour, prefer an integration test that runs the compiled binary and checks its exit code, stdout and stderr.

The Contributor License Agreement#

Hekma is licensed under Apache-2.0, and every contribution is made under the project's Contributor License Agreement. Under it you assign copyright in your contribution to the project owner and get a broad licence back to keep using your own work. Opening a pull request means you accept it. On your first pull request a bot asks you to sign by posting a comment it quotes, and the pull request is not merged until you have. Make sure you have the right to contribute the code, for example that your employer allows it.

Issues#

Open an issue on GitHub using the bug report, feature request or question template. For a bug, include hekma --version, your OS, the command you ran and its full output. For a larger change, such as a new command, a manifest or adapter contract change, or anything that breaks compatibility, open an issue first so the direction can be agreed before you write the code.

Report security vulnerabilities privately through the repository's Security tab, never in a public issue.

Pull requests#

A pull request that is easy to review:

  • explains the problem it solves;
  • stays focused, without unrelated refactoring or formatting changes mixed in;
  • adds or updates tests when behaviour changes;
  • updates documentation when behaviour changes (see below);
  • uses a conventional commit title, such as fix: report the exit code of an adopted agent;
  • passes CI.

Changes to the JSON documents, exit codes or the adapter contract follow the deprecation policy on Status and roadmap. The full rules are in CONTRIBUTING.md, and maintainers cut releases following the release process.

Change these docs#

These docs do not live in the Hekma repository. Ktesio maintains them with the hekma.ktesio.dev site, in a repository that is not public. To report a mistake or a gap, open an issue on Hekma and name the page; if Hekma's behaviour changed, link the Hekma pull request.

Pages describe the latest release, and anything that exists only on Hekma's main branch is marked Unreleased: after 0.11.0. Commands and output on the pages come from real runs of a release build in a throwaway state directory, so a report that includes the command you ran and its output is the fastest to fix.