> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentarea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

# 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 theme={null}
    # 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 theme={null}
    # Start the development environment
    make up-dev

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

  <Step title="Create a Branch">
    ```bash theme={null}
    # 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 theme={null}
    # 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 theme={null}
    // 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 theme={null}
    // 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 theme={null}
# 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 theme={null}
## 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! 🤖✨