Contributing To The Main Repo

This page describes the expected contribution workflow for the main OrcAI repository.

Before You Start

• Use Bun >=1.3.10.
• Prefer the VS Code devcontainer workflow for consistent tooling.
• Create a branch from the latest main branch.

Typical Contribution Flow

1. Sync main branch and create a feature/fix branch.
2. Implement your changes.
3. Run the relevant checks locally.
4. Commit using Conventional Commit format.
5. Open a pull request with clear scope and validation notes.

Branch Naming

Use short, descriptive branch names, for example:

• feat/chat-branch-switcher-fixes
• fix/repository-playground-empty-state
• docs/self-hosting-config-update

Commit Message Format

This repository enforces commit messages through commitlint (@commitlint/config-conventional).

Use Conventional Commits, for example:

• feat(chat): add branch filter to chat list
• fix(workers): handle missing qdrant payload field
• docs(self-hosting): clarify spicedb security modes

Local Validation

Run the complete CI-equivalent validation:

bun run ci

For a faster check while iterating, run:

bun run lint

Additional useful checks:

bun run test
bun run --filter @orcai/web types:check

Git Hooks In This Repo

• pre-commit: runs lint-staged formatting.
• commit-msg: runs commitlint validation.
• pre-push: runs bun run prepush.
• GitHub Actions runs bun run ci for pushes to main and for pull requests.

Pull Request Expectations

Include the following in your PR description:

• What changed and why.
• Risk level and impacted areas (apps/app, apps/workers, apps/web, packages/*).
• Validation performed (commands run and outcomes).
• Screenshots for user-facing UI changes.
• Any TODOs or follow-up work.

Documentation Contributions

If your change modifies user flow, operations, or configuration behaviour:

• Update relevant docs in apps/web/content/docs.
• Keep wording consistent with British English in docs prose.
• Prefer explicit TODO markers over speculative behaviour.

Generated And Derived Files

Some files are generated by tooling (for example TanStack route trees). If your change affects generation inputs, ensure generated outputs are updated accordingly.

Security Reports

Do not open a public issue for a suspected vulnerability. Follow the private reporting process in the repository's SECURITY.md.

Contribution Licence

OrcAI is licensed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). By submitting a contribution, you agree to license it under the same terms and confirm that you have the right to do so. Do not submit code or assets whose licence is incompatible with the AGPL.