Skip to content

Contributing‐Guide

Jump to bottom
Clo edited this page Mar 29, 2026 · 1 revision

Contributing Guide

Development Setup

1. Clone and install

git clone https://github.com/omnuron/omniclaw.git
cd omniclaw
uv sync --extra dev

2. Install pre-commit hooks

pip install pre-commit
pre-commit install

This installs ruff lint and format checks that run automatically before each commit.

3. Verify setup

omniclaw doctor

Branch and PR Workflow

We use a branch protection model. All changes must go through Pull Requests — direct pushes to main are not allowed.

Creating a PR

  1. Create a feature branch from main:

    git checkout main
git pull origin main
git checkout -b feature/your-feature-name

  2. Make your changes and commit:

    git add .
git commit -m "feat: describe your change"

  3. Push and create a PR:

    git push -u origin feature/your-feature-name

    Then open a Pull Request on GitHub.

PR Requirements

Before a PR can be merged, it must:

  • Pass Lint check (ruff lint + format)
  • Pass Test suite (pytest)
  • Receive at least 1 approving review

Commit Message Convention

We follow conventional commits:

Prefix Usage
feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style / formatting
refactor: Code restructuring (no behavior change)
test: Adding or updating tests
ci: CI/CD configuration
chore: Maintenance tasks

Code Quality

Linting

uv run ruff check src/          # Lint check
uv run ruff check src/ --fix    # Auto-fix issues

Formatting

uv run ruff format src/          # Format code
uv run ruff format --check src/  # Check without modifying

Type Checking

uv run mypy src/omniclaw --ignore-missing-imports

Running Tests

uv run pytest                    # Run all tests
uv run pytest -x                 # Stop on first failure
uv run pytest -v                 # Verbose output

Project Structure

omniclaw/
├── src/omniclaw/          # Main source code
│   ├── agent/             # MCP agent server
│   ├── nanopayment/       # EIP-3009 nano transfers
│   ├── trust/             # ERC-8004 trust evaluation
│   ├── cli.py             # CLI commands
│   ├── core.py            # Main OmniClaw client
│   ├── seller.py          # Seller SDK
│   └── config.py          # Configuration
├── tests/                 # Test suite
├── examples/              # Usage examples
├── .github/workflows/     # CI/CD pipelines
├── .pre-commit-config.yaml
├── pyproject.toml
└── README.md

Getting Help

  • Open a GitHub Issue for bugs or feature requests
  • Start a Discussion for questions
  • Check existing issues for good first issue and help wanted labels

Further Reading

Clone this wiki locally