​

Contributing to AgentArea

​

🚀 Quick Start for Contributors

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/agentarea.git
cd agentarea

# Start the development environment
make up-dev

# Verify everything is working
curl http://localhost:8000/health

# Create a feature branch
git checkout -b feature/your-feature-name

​

📋 Ways to Contribute

​

🐛 Reporting Issues

​

Bug Reports

​

Feature Requests

• Use case: What problem does this solve?
• Proposed solution: How should it work?
• Alternatives: What other approaches have you considered?
• Impact: How would this benefit the community?

​

💻 Development Guidelines

​

Code Style

# Use ruff for formatting
uv run ruff format

# Use ruff for linting and import sorting
uv run ruff check --fix

# Use pyright for type checking
uv run pyright

# Follow PEP 8 and use descriptive names
def create_agent_instance(agent_config: AgentConfig) -> Agent:
    """Create a new agent instance with the given configuration."""
    pass

// Use Prettier for formatting
npm run format

// Use ESLint for linting
npm run lint

// Follow naming conventions
interface AgentConfiguration {
  name: string;
  model: string;
  tools: string[];
}

const createAgent = async (config: AgentConfiguration): Promise<Agent> => {
  // Implementation
};

// Use gofmt for formatting
go fmt ./...

// Use golint for linting
golint ./...

// Follow Go conventions
type AgentConfig struct {
    Name  string `json:"name"`
    Model string `json:"model"`
    Tools []string `json:"tools"`
}

func CreateAgent(config AgentConfig) (*Agent, error) {
    // Implementation
}

​

Testing

# Run all Python tests
make agentarea-platform-test
# or
cd agentarea-platform && uv run pytest

# Run specific test suites
cd agentarea-platform && uv run pytest tests/unit/
cd agentarea-platform && uv run pytest tests/integration/
npm test # Frontend tests

# Run Go tests
make test-go
# or
cd agentarea-mcp-manager && go test ./...

​

Documentation

• Code comments: Explain complex logic and business rules
• API documentation: Update OpenAPI specs for API changes
• User documentation: Update guides when adding user-facing features
• README updates: Keep installation and setup instructions current

​

🔄 Pull Request Process

​

Before Submitting

​

PR Template

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added for new functionality

​

Review Process

1. Automated checks: CI/CD pipeline runs tests and linting
2. Code review: Maintainer reviews code and provides feedback
3. Iteration: Address feedback and update PR
4. Approval: Maintainer approves and merges

​

🏗️ Architecture Guidelines

​

Project Structure

agentarea/
├── agentarea-platform/     # Python backend (FastAPI + Temporal)
│   ├── apps/               # API, worker, CLI apps
│   └── libs/               # Domain libraries (uv workspace)
├── agentarea-webapp/       # Next.js frontend + packages
├── agentarea-mcp-manager/  # Go MCP server orchestration
├── agentarea-cli/          # Node.js CLI (Ink/React)
├── charts/                 # Helm charts
├── docs/                   # Mintlify documentation
└── scripts/                # Build/deploy utilities

​

Design Principles

​

🚀 Release Process

1. Actions → “Prepare Release” (patch/minor/major) — opens a release PR that bumps VERSION.
2. Review and merge the PR. ci.yml builds immutable <version>-<sha> Docker images.
3. Locally: ./scripts/release.sh — runs pre-flight checks, creates and pushes vX.Y.Z tag.
4. The tag push triggers retag of the pre-built images to <version>, <maj.min>, <maj>, latest, creates the GitHub Release, and publishes the Helm chart. No rebuild.

​

🤝 Community Guidelines

​

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers and help them learn
• Provide constructive feedback
• Focus on what’s best for the community

​

Communication Channels

​

🎓 Learning Resources

​

For New Contributors

• AgentArea Architecture - Understanding the system design
• Getting Started Guide - Setting up your development environment
• API Reference - Complete API documentation
• Building Agents - Learn how to create AI agents

​

Advanced Topics

• MCP Integration - Model Context Protocol implementation
• Agent Communication - Multi-agent patterns
• Deployment Guide - Production deployment strategies

​

📞 Getting Help