Contributing

May 28, 2026 · View on GitHub

Setup

git clone https://github.com/mlorentedev/hive.git
cd hive
make install

Development

make check    # lint + typecheck + test (run before every PR)
make lint     # ruff only
make typecheck # mypy --strict only
make test     # pytest only
make smoke    # e2e smoke tests (needs Ollama + OPENROUTER_API_KEY)
make build    # full build (runs check first)
make run      # run hive MCP server locally
make site     # build landing page (requires Node.js)
make site-dev # start landing page dev server

Local MCP registration (for development)

# Claude Code
claude mcp add -s user hive -- uv run --directory /path/to/hive hive-vault

# Gemini CLI
gemini mcp add -s user hive-vault uv -- run --directory /path/to/hive hive-vault

Pull Requests

  1. Create a feature branch from master
  2. Follow Conventional Commits (feat:, fix:, docs:, etc.)
  3. Run make check — all gates must pass
  4. Open a PR against master
  5. CI runs automatically:
    • check (ubuntu-latest, Python 3.12 + 3.13): lint + mypy + unit tests + build
    • cross_worker_lock (ubuntu-latest + windows-latest): cross-worker filelock eviction + cancellation race tests (allowed-to-fail for first 14d of CI maturity)
  6. Squash merge after CI passes

Code Standards

  • Python 3.12+, type hints everywhere (mypy --strict)
  • Formatting: Ruff
  • Tests: pytest, TDD preferred (write test first)
  • Functions < 40 lines, nesting < 4 levels

Release Process

Automated via release-please. Merging to master with conventional commits triggers:

  1. Release PR with changelog (auto-created)
  2. Merge Release PR → GitHub Release + PyPI publish (trusted publishing)