Skip to content

Contribution.mdx

Latest commit

 

History

History
184 lines (148 loc) · 8.93 KB

Contribution.mdx

File metadata and controls

184 lines (148 loc) · 8.93 KB
Raw
title Contribution Guide
icon code-pull-request
description Contribute to Omi and earn rewards! Some tasks have paid bounties.

Will this be accepted?

Before you write code, check product fit:

  • Read PRODUCT.md — memory-first loop, one shared chat mind, trust over cleverness, integrations harness, taste floor.
  • Check the product invariant registry. Locked invariants (for example one shared transcript across notch and main chat) are binding; PRs that touch their paths must name the invariant ID.
  • Large or ambiguous features should start as a GitHub issue so maintainers can align on scope and direction before major implementation work begins.

Maintainers declining a PR for direction or taste will cite an invariant ID or open a proposed invariant the same week — so “project direction” stays written down, not tribal.

How to Contribute

Go to [github.com/BasedHardware/Omi](https://github.com/BasedHardware/Omi) and click **Fork**. Clone your fork, create a branch, and implement your changes. Add focused tests and include the commands or manual steps you used to verify the change. Before pushing, draft the PR body and run `make preflight`, then run `scripts/pr-preflight --pr-body-file /path/to/draft-pr-body.md` to validate invariant citations and any required failure-class declaration. Use `scripts/pr-preflight --suggest` before drafting the body to get the paste-ready invariant section and failure-class guidance. The manifest-backed checks are identical locally and in CI. Submit a PR and specify which issue it relates to. Name any product invariants your change affects.

Pull Request Quality

Good PRs are easy to review and come with evidence that the change works.

  • Bug fixes include the regression test that would have caught the bug.
  • Classify reactive fixes. A fix: commit responds to a triggering defect and must declare Failure-Class: FC-<slug> | new | none in its PR body. A harden: commit strengthens a boundary or contract without a triggering incident; it may cite a class but needs no declaration. The validator is offline and required; its report command is advisory and only identifies classes eligible for a maintainer to mark dormant.
  • Keep instance fixes compact. An existing-class declaration replaces the root-cause and durable-guard narrative. Provide that extended narrative only when declaring new, changing a class's canonical prevention primitive or owner, or making a registry-only lifecycle transition. An instance-fix PR never edits registry data. To mark a class dormant, a separate registry-only PR sets status to dormant with a UTC ISO-8601 dormant_since. When report flags a recurrence after that timestamp, merge a separate registry-only reopen PR that sets status to open and removes dormant_since, then classify the instance fix. IDs use stable semantic lower-kebab slugs such as FC-malformed-doc-read; use scripts/failure-class prepare or explain for the exact field and relevant context.
  • Prefer primitives to guards. Before adding a check or ratchet, answer in the PR body: “Why isn't this a shared primitive instead?” A new guard must cite the real merged PR or incident it would have caught; no real instance means the check does not land.
  • Small features can go straight to PR when they are well scoped: test the core path and the main error path, and describe any manual verification you did.
  • Large or ambiguous features should start as a GitHub issue so maintainers can align on scope and direction before major implementation work begins.
  • Show your verification. List the commands you ran and what they showed in the PR description. "It compiles" is not evidence — exercising the real user-facing path is.
  • Tests that run in CI must be hermetic — no live services, no network. Validation against a live service is welcome as extra evidence, but it can never be the only proof a PR works.
  • Behavioral tests execute production behavior. Source-string assertions are static tripwires only; they do not prove lifecycle, concurrency, or integration behavior.
  • Product invariants — if you touch paths listed on a locked invariant, name the ID (for example INV-CHAT-1) in the PR body.
  • Fast local deterministic checks — run make preflight. New deterministic diff-scoped checks belong in .github/checks-manifest.yaml, never directly in workflow YAML.
  • PR metadata contract check — draft the body, then run scripts/pr-preflight --pr-body-file /path/to/draft-pr-body.md. Use scripts/pr-preflight --suggest when you need the paste-ready invariant section. Once the branch has a PR, scripts/pr-preflight reads its current body automatically with gh (or set OMI_PR_BODY_FILE). Pre-push runs these same cheap contracts.

Contributing with an AI agent

Omi is built to be agent-friendly. If you use an AI coding agent, it will automatically pick up AGENTS.md at the repo root (plus per-component guides in backend/, app/, and desktop/macos/). The engineering standards there — especially the Definition of Done checklist — apply to your PR. Rules in that file about maintainer machines and landing on main directly don't apply to fork-based contributions.

Documentation Contributions

Docs contributions are just as important as code contributions! Our docs are located in the GitHub docs folder and sync in real-time with docs.omi.me.

You can edit docs directly from GitHub: Fork the repo → [click the edit icon](https://share.cleanshot.com/dkBSffGr) → click "Preview" → create a pull request.

Contribution Rewards

Get rewarded for approved PRs with significant contributions:

Free DevKit device (necklace or glasses, depending on contribution area) $100 of transcription credits $500 of transcription credits + special Contributor role in Discord Trip to hang out with the Based Hardware team

What Qualifies as a Significant Contribution?

Something you spent 5+ hours on. Can be multiple smaller contributions that add up. Either a new feature or a major bug fix. Quality code with clear explanations, focused tests, and verification notes. To claim your reward, email [team@basedhardware.com](mailto:team@basedhardware.com) with: - List of your contributions - Your address - Email and phone number

Paid Bounties

Get paid to improve AI wearables!

Browse open issues with the "Paid Bounty" label

Bounty Rules

Rule Description
Code must be merged Your code must be merged into the master branch
Eligibility Bounty eligibility is solely at our discretion
Locking a task You can "lock" a bounty task, but only after your first PR is merged
Claiming payment Email team@basedhardware.com with bounty link + PayPal account

No Bounties Available?

If there are no paid bounties available, you can suggest your own:

Filter by [open issues](https://github.com/BasedHardware/Omi/issues?q=is:open+is:issue) without the "bounty" label. Comment on the issue and ping @josancamon19 or @kodjima33 with your bounty suggestion.

Get Started

Browse all open issues View issues with bounties Join the community Contribute to docs