Skip to content

CONTRIBUTING

Contributing to Haven

Thanks for helping improve Haven. This guide covers local development, documentation, and how to submit changes.

Before you start

  • Run commands from the repo root (directory containing Makefile, cli/haven, scripts/).
  • Haven is Apache-2.0. By contributing, you agree your changes are licensed under the same terms.
  • Add the standard SPDX header to new source files — see LICENSE headers.
  • Follow the Code of Conduct.
  • Report security issues privately — see SECURITY.md. Do not file public issues for vulnerabilities.

Developer Certificate of Origin (DCO)

Every commit must be signed off with a Signed-off-by line that certifies you have the right to submit the contribution under the Apache-2.0 license (see developercertificate.org):

git commit -s -m "your message"

Example trailer:

Signed-off-by: Your Name <you@example.com>

Use the same name and email as your GitHub account. PRs without DCO sign-off will not be merged.

Development setup

Identity plane (local cluster)

./deploy/operators/install.sh
make dev
make wait
make doctor
make admin

Keycloak Admin Console: http://auth.127.0.0.1.nip.io/admin

Console (Go + React)

make ui-install          # once
make ui-dev              # Vite → http://localhost:5173
go run ./cmd/haven-console

Tests

make console-test        # Go tests in internal/
go test ./...

Controller

make controller-build
make controller-deploy   # requires cluster + CRDs

Full operator reference: CLI · deployment paths: Runbook.

Documentation

Documentation lives in docs/ and is published with MkDocs Material.

Task Command
Preview locally make docs-serve → http://127.0.0.1:8000
Build static site make docs-build → site/
Doc index README.md

Writing docs

  • Use repo root in examples, not machine-specific paths.
  • Put lab host URLs in lab-host.md; link from other pages instead of duplicating tables.
  • Cross-link related pages with relative paths ([Runbook](runbook.md)).
  • Keep operational content in runbook/tutorials; keep design rationale in architecture/ux.
  • Update mkdocs.yml nav when adding a new doc page.

Published site (after merge to main): https://zyvorai.github.io/haven/

Pull requests

  1. Fork and branch from main.
  2. Keep changes focused — one logical change per PR when possible.
  3. Update docs if you change behavior, CLI flags, deploy paths, or env vars.
  4. Run relevant checks before opening the PR:
make console-test
make docs-build    # if docs changed
  1. Open a PR with:
  2. What changed (brief)
  3. Why (motivation or bug)
  4. Test plan (commands run, screenshots for UI)

Commit messages: imperative mood, concise subject (docs: add MkDocs site, fix: sync CNPG CA before Keycloak apply).

Remote lab host

For console work against the shared lab:

./scripts/deploy-remote.sh <ephemeral-ip> operator

Endpoints and OIDC wiring: lab-host.md.

Questions