Contributing to Heimdall

Thank you for your interest in Heimdall. This page says how to get the code, how to report a bug, and how to propose a change.

Heimdall is a defensive sandbox. Its tests exercise its own containment and nothing outside it; a contribution follows the same rule.

Get the code

Anyone can clone the repository anonymously over SSH. Any SSH key works, and it does not have to be registered:

git clone ssh://anonymous@git.gunnar.rs:2222/nordisk/heimdall.git
cd heimdall
cargo build --release

The main branch is main. Releases are annotated tags (v0.1.0); until the crates are on crates.io, consumers depend on a tag (see docs/API.md).

Report a bug or ask for a feature

Issues live on gunnar.rs, in the repository nordisk/heimdall. You need an account on https://www.gunnar.rs to file an issue: sign up there with a passkey, then open the issue in the console. With the Gunnar CLI, gunnar forge issue open --repo nordisk/heimdall --title … --body … files a signed issue.

If you cannot sign up, write to gunnar@gunnar.rs.

A good bug report gives:

the version (heimdall --version), the tag or the commit, and the build features;
the policy file and the command line, with secrets left out;
what you did, what you expected, and what happened instead;
the refusal code or the error Heimdall printed (for example heimdall-wasm-3 or heimdall-out-1).

Do not report a vulnerability as an issue. Follow SECURITY.md instead.

Propose a change

Start from a fresh main, on a branch of your own.
Make the change in small commits. Each commit message says what changed and why.
Push the branch to a repository of your own on gunnar.rs and open a pull request against main in the console. Contributions come only as pull requests on git.gunnar.rs; patches by e-mail are not taken.
A maintainer reviews the change. It is merged when the review and the checks below are green.

Before your first change is merged, you accept the Contributor License Agreement in CLA.md: your first pull request adds one line to CLA-SIGNATURES.md (see below).

Test first: RED, then GREEN

Every change comes with a test. A bug fix starts with a failing test. Commit the failing test first (its message starts with RED), then the change that makes it pass (GREEN). The reviewer runs the test at both commits. Every test name says what it proves. A new parser gets a property test and a cargo-fuzz target under fuzz/.

Coding rules

scripts/ci.sh is green. It runs cargo fmt --check, clippy with -D warnings, the test suites, the heimdall-plain shim build (when libseccomp is present), cargo deny check and the fuzz smoke runs. Run it in the CI image:
```
podman build -t localhost/nordisk-cargo-toolchain:heim-ci -f ci/ci.Containerfile ci
podman run --rm -v "$PWD":/src -w /src localhost/nordisk-cargo-toolchain:heim-ci scripts/ci.sh
```
The heimdall-plain container tests need privileges and run apart: scripts/plain-tests.sh. Longer fuzzing: scripts/fuzz.sh.
Format with rustfmt; the settings are in rustfmt.toml, the same in every repository of the project.
Clippy is clean: cargo clippy --workspace --all-targets -- -D warnings.
No unsafe in heimdall-core and heimdall-plain (#![forbid(unsafe_code)]). Anywhere else it needs a reason in a comment and in the commit message.
Every source file starts with SPDX-License-Identifier: AGPL-3.0-only.
A new dependency needs a reason in the commit message, must be a well-known crate, and must pass cargo deny --locked check (licences, sources and advisories, see deny.toml).
No secrets in the repository: no private keys, tokens or passwords. Tests make their keys at run time, or use a fixed test seed that is named as such.
Commit messages carry no AI co-author trailers. The forge refuses them.

Licence of contributions

Heimdall is dual licensed: under the GNU Affero General Public License v3.0 only (AGPL-3.0-only), and under a commercial licence (see COMMERCIAL-LICENSING.md). It is owned jointly by Ignalina ApS and Vetra Automation AB.

Because of the dual licence, every outside contribution needs the Contributor License Agreement (CLA) in CLA.md, version 1.1. It grants Ignalina ApS and Vetra Automation AB a licence to your contribution, including the right to license it under the commercial licence as well as under the AGPL, and a licence to any patent of yours that the contribution necessarily uses. You confirm that the contribution is yours to give. You keep the copyright in your contribution.

To accept the CLA, add one line to CLA-SIGNATURES.md in your first pull request, in the form that file shows. This line is the only way to accept the CLA. You accept once; it covers all your contributions. Questions about the CLA: gunnar@gunnar.rs.

Conduct

Be kind and stay on the subject. Criticise code, not people.

nordisk/heimdall

CONTRIBUTING.md