Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (81 loc) · 4.24 KB

CONTRIBUTING.md

File metadata and controls

119 lines (81 loc) · 4.24 KB

Contributing

Contributions are welcome. This document covers development workflows in the Sunbeam monorepo.

Prerequisites

  • macOS or Linux. Windows is not a supported development environment. Windows is a first-class target for end-user products (SBBB desktop, Tauri shells) but contributor tooling is bash-only.
  • Rust stable. Install from rustup.rs.
  • cargo-nextest. Install via cargo install cargo-nextest. The repo uses cargo nextest run, not cargo test.
  • Deno (for apps/driver, apps/kanban, apps/site, apps/estafeta). Install from deno.land.
  • Node 20+ (for libs/beam-ui, libs/storybook). Install from nodejs.org.
  • direnv (recommended). Per-directory environment loading. Install via brew install direnv (macOS) or your package manager.

First clone

git clone --recursive https://src.sunbeam.pt/studio/sunbeam
cd sunbeam
direnv allow
git submodule update --init --recursive
cargo check --workspace --exclude tuwunel

The direnv allow loads environment from .envrc (per-directory). The cargo check verifies the Rust workspace compiles. This takes a few minutes on first run.

Workspace management

Use Git worktrees for per-branch isolation. Each worktree shares the git object database but has its own CARGO_TARGET_DIR, preventing build collisions:

git worktree add ../<branch> -b <branch>
cd ../<branch>
./.hooks/setup

The .hooks/setup script symlinks .env, runs direnv allow, initializes submodules, and pre-caches Node and Deno dependencies.

Building

Full Rust workspace:

cargo check --workspace --exclude tuwunel

Tuwunel (the Matrix homeserver) is excluded because it has conflicting native library dependencies with other workspace members.

Per-workspace member:

cargo build -p <crate-name>

E.g., cargo build -p sunbeam-sdk builds just the SDK crate.

Testing

Rust, all workspace members:

cargo nextest run --workspace --exclude tuwunel

Always use cargo nextest, never cargo test. Nextest runs tests in parallel and provides better output.

Per-crate:

cargo nextest run -p <crate-name>

Integration tests: Tests touching PostgreSQL, Valkey, OpenSearch, or the Matrix homeserver must hit the real services. No mocks for infrastructure-facing code. Mocks have historically masked real bugs that only appear against actual cluster configuration.

Use the shared dev instances (configured in sunbeam.workspace.yaml) when running integration tests locally.

Submodule updates

External submodules under 3p/ and forks/ are pinned to upstream SHAs. To bump one:

cd 3p/tokio
git fetch origin --tags
git checkout <new-tag>
cd ../..
git add 3p/tokio
git commit -m "chore(3p): bump tokio to <new-tag>"

Commit style

Use Conventional Commits: type(scope): description. No emojis. No metrics or counts in commit body.

Examples:

feat(wfe): add retry logic to workflow execution
fix(cli): correct environment variable substitution
docs(sol): update agent architecture diagram

Git hosting

All Sunbeam development — issues, pull requests, CI, releases — happens on the Sunbeam Gitea at src.sunbeam.pt. Any presence of Sunbeam code on GitHub, Codeberg, or elsewhere is a one-way mirror only; contributions go through src.sunbeam.pt.

When searching across the monorepo or querying commit history, use the Gitea MCP tools, not gh. Using gh hits the mirror (at best partial) and skips everything that lives only on Gitea.

Code style

  • Rust: cargo fmt for formatting, cargo clippy -- -D warnings for linting.
  • Node/TypeScript: Follow the configuration in respective tsconfig.json and .eslintrc.
  • Deno: deno fmt and deno lint.

Licensing

Licenses are per-project. Refer to the LICENSE or LICENSE.md file in each project subdirectory. Submodules under 3p/ and forks/ retain the upstream project's license.

Documentation

Questions? Check the main README.md or open an issue on Gitea.