Contributing

Coding agents follow AGENTS.md, which also holds the code conventions in full.

Building

nix develop provides the toolchain (Rust through rustup, pinned to stable 1.95.0 in rust-toolchain.toml) and the native libraries. Build and test the workspace:

cargo build --workspace --release
cargo test --workspace

Build one binary:

cargo build -p tern-core --release
cargo build -p tern --release

Build the Nix packages, as CI does:

nix build .#tern .#tern-core

Checks

CI rejects code that fails any of these:

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

Formatting runs on its own at commit time through a pre-commit hook (.pre-commit-config.yaml). Install it once per clone:

pre-commit install

A commit that the hook reformats stops; stage the changes and commit again.

Conventions — 4-space indentation and trailing commas; imports grouped std, external, local crate; doc comments on every pub function, with an # Errors section when it returns Result; unwrap and expect denied outside tests.

Documentation

The docs compile with tern itself, through two installs of pandoc-template in .tern/config.toml: one for docs/, one for the top-level README.md. Reinstall the templates after changing that file:

nix develop path:.#docs --command tern -u

Compile docs/ and README.md into docs-html/:

nix develop path:.#docs --command tern

Releases

Commits follow the Angular convention, and the prefixes decide releases. On every push to master, CI (.forgejo/workflows/ci.yml) reads the commits since the last v* tag:

Commits since the last tag Release
A breaking change (feat!:, BREAKING CHANGE:) Major
A feat: Minor
A fix: or perf: Patch
Anything else (docs:, chore:, ci:, refactor:, …) None: CI stops before building

For a release, CI bumps [workspace.package] version in Cargo.toml (both crates and flake.nix read it from there), runs the checks, builds both packages, pushes them to the yuuhikaze Cachix cache, then commits chore(release): v<version> [skip ci] and tags it. Pull requests run the checks and report the version a merge would release; they never publish.

Cachix token — the push needs a token scoped to the cache, stored as the CACHIX_AUTH_TOKEN secret under the repository’s Settings → Actions → Secrets. Generate it at https://app.cachix.org/cache/yuuhikaze/settings/authtokens. Without it, a releasing run fails with an explicit message.

Manual push — when CI is unavailable, push and check a build by hand:

cachix authtoken <token>
nix build .#tern .#tern-core
cachix push yuuhikaze "$(readlink -f result)" "$(readlink -f result-1)"
nix path-info --store https://yuuhikaze.cachix.org "$(readlink -f result)" "$(readlink -f result-1)"