Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
334 lines (251 loc) · 7.25 KB

CONTRIBUTING.md

File metadata and controls

334 lines (251 loc) · 7.25 KB

Contributing to PolyAgent

First off, thank you for considering contributing to PolyAgent! It's people like you that make PolyAgent such a great tool for the AI community.

🎯 Ways to Contribute

There are many ways to contribute to PolyAgent:

  • Report Bugs - Help us identify and fix issues
  • Suggest Features - Share your ideas for new capabilities
  • Improve Documentation - Help make our docs clearer and more comprehensive
  • Submit Code - Fix bugs or add new features
  • Answer Questions - Help other users in discussions
  • Write Tutorials - Share your PolyAgent use cases and patterns

🚀 Getting Started

Prerequisites

  • Go 1.24+ for orchestrator development
  • Rust (stable) for agent core development
  • Python 3.11+ for LLM service development
  • Docker and Docker Compose
  • protoc (Protocol Buffers compiler)

Development Setup

  1. Fork and Clone

    git clone https://github.com/your-username/shannon.git
cd shannon

  2. Set Up Development Environment

    # Install dependencies
make setup-dev

# Copy and configure environment
make setup-env
vim .env  # Add your API keys

  3. Start Services for Development

    # Start all dependencies (DB, Redis, etc.)
docker compose -f deploy/compose/docker-compose.yml up -d postgres redis qdrant temporal

# Run services locally for development
# Terminal 1: Orchestrator
cd go/orchestrator
go run ./cmd/server

# Terminal 2: Agent Core
cd rust/agent-core
cargo run

# Terminal 3: LLM Service
cd python/llm-service
python -m uvicorn main:app --reload

🔨 Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

2. Make Your Changes

Code Style Guidelines

Go (Orchestrator)

  • Follow standard Go formatting (gofmt)
  • Use meaningful variable names
  • Add comments for exported functions
  • Run go mod tidy after adding dependencies

Rust (Agent Core)

  • Follow Rust formatting (cargo fmt)
  • Use clippy for linting (cargo clippy)
  • Prefer Result over panics
  • Document public APIs

Python (LLM Service)

  • Follow PEP 8 style guide
  • Use type hints
  • Format with black
  • Sort imports with isort

Protocol Buffers

  • After modifying .proto files: 
    make proto

3. Write Tests

All code changes should include tests:

# Go tests
cd go/orchestrator
go test -race ./...

# Rust tests
cd rust/agent-core
cargo test

# Python tests
cd python/llm-service
python -m pytest

4. Run CI Checks Locally

Before submitting, ensure all checks pass:

# Run all CI checks
make ci

# Individual checks
make lint
make test
make build

5. Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "feat: add new pattern for recursive agents

- Implement RecursivePattern in orchestrator
- Add tests for edge cases
- Update documentation"

Commit message format:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Test additions/changes
  • chore: Maintenance tasks

6. Push and Create Pull Request

git push origin feature/your-feature-name

Then open a Pull Request on GitHub with:

  • Clear title and description
  • Link to any related issues
  • Screenshots/logs if applicable
  • Test results

📋 Pull Request Checklist

  • Code follows the project's style guidelines
  • Self-review completed
  • Tests added/updated and passing
  • Documentation updated if needed
  • make ci passes locally
  • No new warnings or errors
  • Commits are logical and atomic
  • PR description explains the changes

🧪 Testing Guidelines

Unit Tests

  • Test individual functions and methods
  • Mock external dependencies
  • Aim for >80% code coverage

Integration Tests

  • Test component interactions
  • Use test containers for dependencies
  • Cover critical paths

E2E Tests

  • Test complete workflows
  • Verify system behavior
  • Test error scenarios

Running Specific Tests

# Test a specific workflow
./scripts/submit_task.sh "test query" | jq .workflow_id
make replay-export WORKFLOW_ID=<id> OUT=test.json
make replay HISTORY=test.json

# Run E2E smoke tests
make smoke

🐛 Reporting Issues

Before Submitting an Issue

  1. Check existing issues to avoid duplicates
  2. Try the latest version
  3. Collect relevant information:
    • PolyAgent version
    • OS and environment
    • Error messages and logs
    • Steps to reproduce

Issue Template

**Description**
Clear description of the issue

**Steps to Reproduce**
1. Run command X
2. See error Y

**Expected Behavior**
What should happen

**Actual Behavior**
What actually happens

**Environment**
- PolyAgent version:
- OS:
- Go/Rust/Python version:

**Logs**

Relevant log output

🏗️ Project Structure

Understanding the codebase:

shannon/
├── go/orchestrator/      # Temporal workflows and orchestration
│   ├── internal/        # Core orchestrator logic
│   ├── cmd/            # Entry points
│   └── tests/          # Go tests
├── rust/agent-core/     # WASI runtime and tool execution
│   ├── src/            # Rust source code
│   └── tests/          # Rust tests
├── python/llm-service/  # LLM providers and MCP tools
│   ├── providers/      # LLM provider implementations
│   ├── tools/          # MCP tool implementations
│   └── tests/          # Python tests
├── protos/             # Protocol buffer definitions
├── config/             # Configuration files
├── scripts/            # Utility scripts
└── docs/               # Documentation

🔧 Debugging Tips

Enable Debug Logging

# Set log levels
export RUST_LOG=debug
export LOG_LEVEL=debug

# View service logs
docker compose logs -f orchestrator
docker compose logs -f agent-core
docker compose logs -f llm-service

Common Issues

Proto changes not reflected:

make proto
docker compose build
docker compose up -d

Temporal workflow issues:

temporal workflow describe --workflow-id <id> --address localhost:7233

Database queries:

docker compose exec postgres psql -U shannon -d shannon

💬 Communication

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and ideas
  • Discord: Real-time chat (coming soon)
  • Pull Requests: Code contributions

🎓 Learning Resources

📜 Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

🙏 Recognition

Contributors are recognized in:

  • The README.md contributors section
  • Release notes
  • Our website (coming soon)

Questions?

Feel free to open an issue with the question label or start a discussion!

Thank you for contributing to PolyAgent! Together we're building the future of AI agents. 🚀