Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
305 lines (233 loc) · 8.05 KB

CONTRIBUTING.md

File metadata and controls

305 lines (233 loc) · 8.05 KB

Contributing to Agora

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

Code of Conduct

This project and everyone participating in it is governed by the principle of respect and professionalism. By participating, you are expected to uphold this code.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Provide specific examples to demonstrate the steps
  • Describe the behavior you observed and what behavior you expected
  • Include screenshots if possible
  • Include your environment details (OS, Node.js version, browser, etc.)

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

  • Use a clear and descriptive title
  • Provide a step-by-step description of the suggested enhancement
  • Provide specific examples to demonstrate the steps
  • Describe the current behavior and the behavior you expected to see
  • Explain why this enhancement would be useful

Pull Requests

  1. Fork the repo and create your branch from main
  2. Install dependencies: cd frontend && npm install
  3. Make your changes
  4. Add tests if you've added code that should be tested
  5. Ensure the test suite passes: npm run test:e2e
  6. Format your code: npm run lint
  7. Commit your changes using conventional commits (see below)
  8. Push to your fork and submit a pull request

Development Setup

Prerequisites

  • Node.js 20+
  • Python 3.12+
  • Git
  • Vercel CLI (for testing serverless functions locally)

Local Development

  1. Clone your fork:
git clone https://github.com/YOUR_USERNAME/agora.git
cd agora
  1. Set up environment variables:
cp .env.example .env
# Edit .env with your API keys
  1. Install frontend dependencies:
cd frontend
npm install
  1. Install Python dependencies:
pip install -r requirements.txt
  1. Run locally:
# Frontend (Next.js)
cd frontend && npm run dev

# Backend (Python serverless via Vercel)
vercel dev

Project Structure

agora/
├── frontend/           # Next.js 15 frontend
│   ├── app/            # App Router pages
│   ├── components/     # React components
│   ├── lib/            # Utilities, API clients, hooks
│   └── tests/          # Playwright E2E tests
├── api/                # Python serverless functions
│   ├── *.py            # API endpoints
│   └── _lib/           # Shared utilities
├── backend/            # Legacy FastAPI (for reference)
├── .github/workflows/  # CI/CD pipelines
└── requirements.txt    # Python dependencies

Coding Guidelines

TypeScript/React

  • Use functional components with hooks
  • Use TypeScript for all new code (strict mode)
  • Follow Next.js App Router conventions
  • Use shadcn/ui components for UI primitives
  • Use React Query for server state management
  • Follow the existing code style (2 spaces, single quotes)

Python

  • Use Python 3.12 features
  • Follow PEP 8 style guide
  • Use type hints for all functions
  • Use async/await for I/O operations
  • Keep functions small and focused
  • Add docstrings to all public functions

Naming Conventions

  • Files: kebab-case.tsx, snake_case.py
  • Components: PascalCase
  • Functions: camelCase (TS), snake_case (Python)
  • Constants: UPPER_SNAKE_CASE
  • Types/Interfaces: PascalCase

Commit Message Guidelines

We use Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, missing semi-colons, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

feat(chat): add support for file uploads
fix(api): resolve SSE streaming timeout issue
docs(readme): update deployment instructions
test(e2e): add tests for agent selection

Testing

Running Tests

# E2E tests (Playwright)
cd frontend
npm run test:e2e

# With UI mode
npm run test:e2e:ui

# Specific test file
npx playwright test tests/01-frontend.spec.ts

Writing Tests

  • Frontend tests: Use Playwright for E2E tests
  • Backend tests: Use pytest for unit tests
  • Test naming: Describe what the test does, not how it does it
  • Test coverage: Aim for >80% coverage on new code

Example Playwright test:

test('should display agent selector', async ({ page }) => {
  await page.goto('/');
  const agentSelector = page.locator('[data-testid="agent-selector"]');
  await expect(agentSelector).toBeVisible();
});

Adding a New Agent

  1. Create agent file in api/_lib/agents/:
# api/_lib/agents/my_agent.py
from .base_primitive import BasePrimitive

class MyAgent(BasePrimitive):
    def __init__(self):
        super().__init__(
            name="my_agent",
            description="What my agent does",
            system_prompt="You are a helpful agent that..."
        )

    async def run(self, query: str, **kwargs):
        # Your agent logic here
        pass

  1. Register agent in orchestrator (if needed)

  2. Add tests for your agent:

# api/_lib/agents/test_my_agent.py
import pytest
from .my_agent import MyAgent

@pytest.mark.asyncio
async def test_my_agent():
    agent = MyAgent()
    response = await agent.run("test query")
    assert response is not None
  1. Update documentation in README.md

Adding a New API Endpoint

  1. Create endpoint file in api/:
# api/my-endpoint.py
from http.server import BaseHTTPRequestHandler
import json

class handler(BaseHTTPRequestHandler):
    def do_GET(self):
        response = {"status": "ok"}
        self.send_response(200)
        self.send_header('Content-type', 'application/json')
        self.end_headers()
        self.wfile.write(json.dumps(response).encode())
  1. Add tests in frontend/tests/:
test('should return correct response from my-endpoint', async ({ request }) => {
  const response = await request.get('/api/my-endpoint');
  expect(response.status()).toBe(200);
  const data = await response.json();
  expect(data.status).toBe('ok');
});
  1. Update API.md with endpoint documentation

Pull Request Process

  1. Ensure all tests pass locally
  2. Update documentation if needed
  3. Add yourself to the contributors list (we'll do this for you!)
  4. Submit PR with a clear description:
    • What changes were made
    • Why the changes were necessary
    • How to test the changes
    • Any breaking changes
  5. Respond to review feedback promptly
  6. Squash commits before merging (we'll help with this)

CI/CD Pipeline

All pull requests trigger:

  • Linting (ESLint, Black, Flake8)
  • Type checking (TypeScript)
  • Tests (Playwright E2E, pytest)
  • Build (Next.js production build)

Make sure all checks pass before requesting review.

Release Process

Releases are handled by maintainers:

  1. Update version in package.json and README.md
  2. Update CHANGELOG.md
  3. Create release tag: git tag -a v0.3.0 -m "Release v0.3.0"
  4. Push tag: git push origin v0.3.0
  5. Create GitHub release with notes
  6. Deploy to production via Vercel

Getting Help

Recognition

Contributors will be recognized in:

  • README.md contributors section
  • GitHub contributors page
  • Release notes

Thank you for contributing to Agora! 🚀