Skip to content

Contributing

Jump to bottom
Kris Armstrong edited this page May 19, 2026 · 2 revisions

Contributing

Toolchain

Tool Version
Go 1.26.3
Node 25.2.1
TypeScript 5.9.3
React 19
Tailwind CSS v4
C C23 (gcc-13 / clang-18)
DPDK 23.11 LTS (Linux only)

Pinned everywhere. Use nvm / fnm / mise against .nvmrc.

Dev setup

git clone git@github.com:krisarmstrong/stem.git
cd stem

make build      # full build (frontend + backend + C dataplane on Linux)
make dev-run    # foreground run with raw-socket capabilities set automatically

make dev-run handles the capability dance:

  • Linux: sudo setcap cap_net_raw,cap_net_admin+ep ./bin/stem once per build, then runs unprivileged
  • macOS: sudo ./bin/stem web (no userspace fcaps)

UI-only iteration: cd ui && npm run dev against a running daemon.

Branch flow

  • main is protected. PRs only.
  • Branch names: feat/, fix/, chore/, docs/, refactor/, test/, ci/
  • Commits are Conventional Commits — commitlint enforces.
  • release-please opens release PRs automatically.

CI

PR CI uses path filters (Changed paths job at the top of ci.yml). A docs-only PR skips Backend, Frontend, E2E, etc.

Required for merge:

  • Backend (Go), Frontend (TypeScript), Quality Checks, Security Scanning, C Lint (C23), Documentation Quality, i18n Validation, Build (linux-amd64), CI Complete

Advisory:

  • E2E Browser Tests, Lighthouse Audit, additional Build matrix rows

Code rules (from CLAUDE.md)

  • TypeScript strict, no any
  • Go: golangci-lint v2.12.1 (pinned, zero warnings)
  • C23 only — no legacy C; clang-format on save; clang-tidy clean; cppcheck warning-free
  • No //nolint or biome-ignore without explicit approval
  • No hardcoded secrets — env vars only
  • Pin exact dep versions (no ^, no ~)
  • Tests: integration paths touching the C dataplane use the Y1731Dataplane interface and are mocked in unit tests

Local checks before pushing

make lint        # Go + C linters + Biome
make lint-c      # clang-tidy + cppcheck only
make test        # all unit tests
make test-e2e    # Playwright suite
make format      # auto-fix formatting
make verify      # full local CI gate

Questions

Open a Discussion. Issues are for confirmed bugs / feature requests.

Clone this wiki locally