Contributing

Development Setup

git clone https://github.com/styrene-lab/omegon.git
cd omegon
cd core && cargo build -p omegon
cargo test -p omegon

Branch Policy

Trunk-based development on main. No long-lived feature branches.

• Direct commits to main for single-file fixes, typos, config tweaks
• Feature branches (feature/<name>) for multi-file work — must merge within one week
• No branch may accumulate more than ~50 commits before merging. If it does, decompose it.

Conventional Commits

All commits must follow the Conventional Commits spec:

feat(tui): surface SegmentMeta as response header tag
fix(providers): handle rate-limit 429 with exponential backoff
chore(release): 0.15.9-rc.14
refactor(memory): extract semantic search into separate module
docs: update provider matrix in FAQ
test: add snapshot test for rounded borders

Testing Requirements

• Every non-trivial code change must include tests
• cargo test -p omegon must pass with zero failures
• cargo check must produce zero warnings
• Snapshot tests (via cargo-insta) are accepted with cargo insta test --accept
• Tests must pass before merge

Release Workflow

Releases use the just task runner:

# Cut a release candidate (bump, test, commit, tag, build, sign)
just rc

# Sign the local macOS validation binary with Apple Developer ID (YubiKey — optional)
just sign

# Publish refs and trigger CI-built release artifacts
just publish

# Cut a stable release (strip -rc.N suffix)
just release

What just publish Does

1. Pre-flight: verifies clean working tree, binary exists, tag exists, version matches
2. Pushes to origin with tags — triggers three CI workflows:
   • release.yml — builds distributable binaries for 4 platforms, signs release archives with cosign, and creates the GitHub Release
   • site.yml — rebuilds docs site, pushes container to GHCR, ArgoCD auto-deploys
3. Builds docs site locally (verification)
4. Links the local binary to /opt/homebrew/bin/omegon
5. Runs post-publish smoke test

just sign and just publish operate in different trust boundaries: just sign signs the operator's local macOS validation binary with Apple Developer ID, while the downloadable release artifacts and downstream package updates are produced from CI-built GitHub release assets.

Crate Structure

Feature Proposals

New features should start with a design tree node, not a PR. Use design_tree_update(create) to propose a new exploration, add research and open questions, and let the design converge before writing code. This prevents throwaway work and ensures architectural coherence.