Contributing

Development Setup

git clone https://github.com/styrene-lab/omegon.git
cd omegon
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.22.0
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
• just test-rust must pass before landing code changes
• just lint must pass with 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 the stable release tag and build the local release binary
# Sign the local macOS validation binary with Apple Developer ID (YubiKey — optional)
# Publish refs and trigger CI-built release artifacts
just release
just sign
just publish

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 and deploys the docs site to omegon.styrene.io
3. Builds docs site locally (verification)
4. Refreshes the local development aliases through just link
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.