Contributing to Blackrim Vox¶

Thanks for your interest in contributing. This page covers everything you need to send a change upstream — from signing your commits to the release cadence.

1. Developer Certificate of Origin (DCO)¶

Blackrim Vox uses the Developer Certificate of Origin instead of a CLA. Every commit must carry a Signed-off-by trailer with your real name and a valid email address:

Signed-off-by: Jane Doe <[email protected]>

The sign-off certifies that you wrote the change yourself, or have the right to submit it under the project's Apache 2.0 license. The full text of the DCO is at https://developercertificate.org/.

Add the trailer automatically with git commit -s:

git commit -s -m "feat: add SMTP sink"

To configure git to sign off every commit automatically:

git config --global format.signOff true

CI rejects commits that are missing a valid sign-off.

2. Dev setup¶

Prerequisites¶

Go 1.22+
make
Docker (optional — required only for the dev-container path)

Clone and build¶

git clone https://github.com/Blackrim-Vox/blackrim-vox.git
cd blackrim-vox
make build

Run the test suite¶

make test

Validate air-gap and telemetry constraints¶

The project enforces two hard rules during CI:

Target	What it checks
`make check-air-gap`	No outbound network calls in the core library
`make check-no-telemetry`	No telemetry, analytics, or phone-home code paths

Run both before opening a PR:

make check-air-gap
make check-no-telemetry

Dev-container shortcut (macOS / Linux with Docker)¶

Install VS Code and the Dev Containers extension.
Clone the repo and open it with code <dir> — VS Code will prompt to reopen in the container.
Inside the container make test passes without any manual setup.

For macOS without Docker, run make dev-deps then make dev for a live-reload loop. See docs/development/dev-container.md for full details.

3. Code style¶

gofmt — all Go files must be formatted before commit (make fmt runs it project-wide).
Simple, incremental commits — each commit should compile, pass tests, and have a single logical purpose. Keep commits small; reviewers read them individually.
No merge commits in PRs — rebase onto main before opening or updating a pull request. The merge button on GitHub is configured for squash-merge; intermediate merge commits inside a PR branch are noise.
Match surrounding style rather than introducing new patterns without discussion.

4. Testing¶

Rule	Detail
Race detector	All tests run with `-race`. A test that passes only without the race detector is broken.
Table-driven tests	Prefer `[]struct{ name, input, want string }` tables over one test function per case.
No network in unit tests	Unit tests must work offline. Use interface fakes for external systems.
Fakes over mocks	Implement a lightweight fake (a struct that satisfies the interface) instead of a generated mock. Mocks couple tests to implementation details.

Run the full suite with the race detector:

go test -race ./...

Or via make:

make test   # equivalent, includes race detector

5. Bd workflow¶

This project uses bd (beads) for issue tracking. When you work on a task:

Claim before working — bd update <id> --claim prevents two contributors from racing the same issue.
File dependencies — if your work unblocks or blocks another issue, link them: bd dep add <child> <parent>.
Update with notes on completion — when you open a PR, add a note so the issue stays current:
```
bd update <id> --notes "PR <url> — SHA <sha>."
```
Close when merged — once the PR lands, bd close <id> --reason "Merged in PR #N.".

Quick reference:

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work

6. Release process¶

OSS releases¶

OSS releases follow semantic versioning. Tags are pushed from main by a maintainer after CI is green:

git tag vX.Y.Z
git push origin vX.Y.Z

The tag triggers the release workflow which builds binaries, generates a changelog from conventional commits, and publishes a GitHub Release.

Enterprise releases¶

The enterprise repository pins a specific OSS version via go.mod. Enterprise releases are version-stamped independently (e.g. enterprise-vX.Y.Z) and reference the OSS tag they build on top of. Contributors to the OSS project do not manage enterprise releases.

Conventional commit prefixes¶

Prefix	Meaning
`feat:`	New user-visible feature (triggers minor bump)
`fix:`	Bug fix (triggers patch bump)
`docs:`	Documentation only — no binary change
`refactor:`	Internal restructuring, no behavior change
`test:`	Test-only change
`chore:`	Build tooling, dependency bumps, CI
`feat!:` / `fix!:`	Breaking change (triggers major bump)

7. Where to find things¶

Topic	Location
Architecture overview	`docs/architecture/`
Operations runbooks	`docs/operations/`
Concept explanations	`docs/concepts/`
Getting-started guide	`docs/getting-started/`
API reference	`docs/reference/`
Guides (how-tos)	`docs/guides/`
Open/enterprise feature split	`docs/editions.md`
Security disclosure	`SECURITY.md`
Issue tracker (bd)	Run `bd ready` in a local checkout

Project scope¶

Blackrim Vox is the open core — capture, segmentation, transcription, routing, the open sinks (S3-compatible, email, local file, BYOK LLM), and the adapter contracts. Enterprise features (RBAC, SAML/OIDC, audit logs, automated reporting, premium plugins) live in a separate repository under a commercial license and are not accepted here as contributions.