# Contributing to AgentArea

<Info>
Thank you for your interest in contributing to AgentArea! This guide will help you get started with contributing to our open-source AI agents platform.
</Info>

## 🚀 Quick Start for Contributors

<Steps>
  <Step title="Fork & Clone">
    ```bash
    # Fork the repository on GitHub, then clone your fork
    git clone https://github.com/YOUR_USERNAME/agentarea.git
    cd agentarea
    ```
  </Step>

  <Step title="Set Up Development Environment">
    ```bash
    # Start the development environment
    make up-dev

    # Verify everything is working
    curl http://localhost:8000/health
    ```
  </Step>

  <Step title="Create a Branch">
    ```bash
    # Create a feature branch
    git checkout -b feature/your-feature-name
    ```
  </Step>

  <Step title="Make Your Changes">
    Follow our coding standards and add tests for your changes
  </Step>
</Steps>

## 📋 Ways to Contribute

<CardGroup cols={2}>
  <Card title="Code Contributions" icon="code">
    - Bug fixes and new features
    - Performance improvements
    - Documentation updates
    - Test coverage improvements
  </Card>

  <Card title="Community Contributions" icon="users">
    - Bug reports and feature requests
    - Documentation improvements
    - Community support and discussions
    - Translation and localization
  </Card>
</CardGroup>

## 🐛 Reporting Issues

### Bug Reports

When reporting bugs, please include:

<Accordion>
  <AccordionItem title="Environment Information">
    - Operating system and version
    - Docker version
    - AgentArea version
    - Python version (if applicable)
  </AccordionItem>

  <AccordionItem title="Reproduction Steps">
    - Clear steps to reproduce the issue
    - Expected vs actual behavior
    - Error messages and logs
    - Screenshots if applicable
  </AccordionItem>

  <AccordionItem title="Additional Context">
    - Configuration files (sanitized)
    - Network setup or special environments
    - Any workarounds you've tried
  </AccordionItem>
</Accordion>

### Feature Requests

For feature requests, please describe:
- **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

<Tabs>
  <Tab title="Python (Backend)">
    ```python
    # 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
    ```
  </Tab>

  <Tab title="TypeScript (Frontend)">
    ```typescript
    // 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
    };
    ```
  </Tab>

  <Tab title="Go (MCP Manager)">
    ```go
    // 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
    }
    ```
  </Tab>
</Tabs>

### Testing

<CardGroup cols={2}>
  <Card title="Unit Tests" icon="test-tube">
    - Write tests for all new functionality
    - Maintain >80% code coverage
    - Use descriptive test names
    - Mock external dependencies
  </Card>

  <Card title="Integration Tests" icon="link">
    - Test API endpoints end-to-end
    - Test agent communication flows
    - Test MCP server interactions
    - Use test fixtures and factories
  </Card>
</CardGroup>

```bash
# 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

<Checklist>
  - [ ] Tests pass locally (`make test`)
  - [ ] Code follows style guidelines (`make lint`)
  - [ ] Documentation is updated
  - [ ] Commit messages are descriptive
  - [ ] Branch is up to date with main
</Checklist>

### PR Template

```markdown
## 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

<CardGroup cols={2}>
  <Card title="Modularity" icon="puzzle">
    - Loosely coupled components
    - Clear interfaces and contracts
    - Plugin-based architecture
    - Dependency injection
  </Card>

  <Card title="Scalability" icon="trending-up">
    - Horizontal scaling support
    - Async/await patterns
    - Efficient resource usage
    - Caching strategies
  </Card>
</CardGroup>

## 🚀 Release Process

We follow [Semantic Versioning](https://semver.org/). Releases use a
**build-once / promote-on-tag** model:

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.**

See [VERSIONING.md](./VERSIONING.md) for the full process, tag semantics, invariants, and troubleshooting.

## 🤝 Community Guidelines

### Code of Conduct

We follow the [Contributor Covenant](https://www.contributor-covenant.org/):
- Be respectful and inclusive
- Welcome newcomers and help them learn
- Provide constructive feedback
- Focus on what's best for the community

### Communication Channels

<CardGroup cols={3}>
  <Card title="GitHub Issues" icon="github">
    Bug reports, feature requests, and project discussions
  </Card>

  <Card title="GitHub Discussions" icon="message-circle">
    Community discussions, support, and collaboration
  </Card>

  <Card title="GitHub Discussions" icon="chat">
    Design discussions, Q&A, and community announcements
  </Card>
</CardGroup>

## 🎓 Learning Resources

### For New Contributors

- [AgentArea Architecture](/architecture) - Understanding the system design
- [Getting Started Guide](/getting-started) - Setting up your development environment
- [API Reference](/api-reference) - Complete API documentation
- [Building Agents](/building-agents) - Learn how to create AI agents

### Advanced Topics

- [MCP Integration](/mcp-integration) - Model Context Protocol implementation
- [Agent Communication](/agent-communication) - Multi-agent patterns
- [Deployment Guide](/deployment) - Production deployment strategies

## 📞 Getting Help

<Note>
**Stuck on something?** Don't hesitate to ask for help:

- **GitHub Issues**: For bug reports and feature requests
- **GitHub Discussions**: For community support and design questions
- **Documentation**: Check our comprehensive guides and API reference

We're here to help you succeed in contributing to AgentArea! 🚀
</Note>

---

Thank you for contributing to AgentArea and helping us build the future of AI agent platforms! 🤖✨