diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7674455a..320f35ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,589 @@ -# Contributions +# Contributing to Flo AI -FloAI is open-source and we welcome contributions. If you're looking to contribute, please: +Thank you for your interest in contributing to Flo AI! We welcome contributions from the community and are excited to work with you. -Fork the repository. -Create a new branch for your feature. -Add your feature or improvement. -Send a pull request. +This guide will help you get started with contributing to the Flo AI project. Please read it carefully before making your first contribution. -We appreciate your input! +> **Note**: This contributing guide currently focuses on **Flo AI**, the core agent building and orchestration library. **Wavefront AI** (the enterprise middleware platform) is currently in development and will be open-sourced in the future. When Wavefront AI is released, we will update this guide with additional contribution guidelines for the middleware platform. -## Installing Dependencies +--- -```cmd +## πŸ“‹ Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Environment Setup](#development-environment-setup) +- [Project Structure](#project-structure) +- [Development Workflow](#development-workflow) +- [Code Style and Standards](#code-style-and-standards) +- [Testing Guidelines](#testing-guidelines) +- [Documentation Guidelines](#documentation-guidelines) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [Types of Contributions](#types-of-contributions) +- [Questions and Support](#questions-and-support) + +--- + +## πŸ“œ Code of Conduct + +This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to vishnu@rootflo.ai. + +--- + +## πŸš€ Getting Started + +### Prerequisites + +Before you begin, ensure you have: + +- **Python 3.10 or higher** (check with `python --version`) +- **Git** installed and configured +- **uv** package manager (recommended) or **pip/poetry** +- **API keys** for LLM providers (for testing): + - OpenAI API key (optional, for OpenAI tests) + - Anthropic API key (optional, for Claude tests) + - Google API key (optional, for Gemini tests) + +### Fork and Clone + +1. **Fork the repository** on GitHub +2. **Clone your fork**: + ```bash + git clone https://github.com/your-username/wavefront.git + cd wavefront + ``` +3. **Add upstream remote**: + ```bash + git remote add upstream https://github.com/rootflo/wavefront.git + ``` + +--- + +## πŸ› οΈ Development Environment Setup + +### Python Environment + +We recommend using `uv` for dependency management: + +#### For contributing to flo-ai: + +```bash +# Install uv if you haven't already +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Navigate to flo_ai directory +cd flo_ai + +# Sync dependencies (installs all dependencies including dev dependencies) uv sync + +# Activate the virtual environment +source .venv/bin/activate # On macOS/Linux +# or +.venv\Scripts\activate # On Windows +``` + +Alternatively, using pip: + +```bash +# Navigate to flo_ai directory +cd flo_ai + +# Install in development mode +pip install -e . + +# Install development dependencies +pip install -e ".[dev]" +``` +For contributing to wavefront: + +```bash +# Install uv if you haven't already +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Navigate to flo_ai directory +cd wavefront + +# Sync dependencies (installs all dependencies including dev dependencies) +uv sync --all-packages + +# Activate the virtual environment +source .venv/bin/activate # On macOS/Linux +# or +.venv\Scripts\activate # On Windows +``` + +### Environment Variables + +Set up your API keys for testing (create a `.env` file or export them): + +[Documentation to be added soon] + +### Verify Installation + +Test your installation: + +```bash +# Run the test suite +pytest tests/unit-tests/ + +# Run a specific test +pytest tests/unit-tests/test_agent_builder_tools.py +``` + +## πŸ“ Project Structure + +Understanding the project structure will help you navigate the codebase: + +[To be added] + +--- + +## πŸ”„ Development Workflow + +### 1. Create a Branch + +Always create a new branch for your work: + +```bash +# Update your local main branch +git checkout main +git pull upstream main + +# Create a new branch +git checkout -b feature/your-feature-name +# or +git checkout -b fix/your-bug-fix +# or +git checkout -b docs/your-documentation-update +``` + +**Branch naming conventions:** +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation updates +- `refactor/` - Code refactoring +- `test/` - Test additions or updates +- `chore/` - Maintenance tasks + +### 2. Make Your Changes + +- Write clean, maintainable code +- Follow the code style guidelines (see below) +- Add tests for new features +- Update documentation as needed +- Keep commits focused and atomic + +### 3. Test Your Changes + +```bash +# Run all tests +pytest + +# Run specific test file +pytest tests/unit-tests/test_your_file.py + +# Run with coverage +pytest --cov=flo_ai --cov-report=html + +# Run integration tests (requires API keys) +pytest tests/integration-tests/ -m integration +``` + +### 4. Commit Your Changes + +Use [Conventional Commits](https://www.conventionalcommits.org/) format: + +```bash +git commit -m "feat: add new feature description" +git commit -m "fix: resolve bug in agent builder" +git commit -m "docs: update contributing guide" +``` + +**Commit types:** +- `feat:` - New feature +- `fix:` - Bug fix +- `docs:` - Documentation changes +- `style:` - Code style changes (formatting, etc.) +- `refactor:` - Code refactoring +- `test:` - Test additions or updates +- `chore:` - Maintenance tasks +- `perf:` - Performance improvements +- `ci:` - CI/CD changes + +### 5. Keep Your Branch Updated + +Regularly sync with upstream: + +```bash +git fetch upstream +git rebase upstream/main +``` + +### 6. Push and Create Pull Request + +```bash +# Push to your fork +git push origin feature/your-feature-name + +# Then create a Pull Request on GitHub +``` + +--- + +## πŸ’» Code Style and Standards + +### Python Code Style + +We use **pre-commit hooks** to ensure code quality. Set it up: + +```bash +# Install pre-commit +pip install pre-commit + +# Install hooks +pre-commit install + +# Run on all files (optional, but recommended) +pre-commit run --all-files +``` + +**Key style guidelines:** + +1. **Follow PEP 8** - Python style guide +2. **Type hints** - Use type hints for function signatures: + ```python + from typing import Optional, List + + async def process_data( + items: List[str], + limit: Optional[int] = None + ) -> dict: + ... + ``` +3. **Docstrings** - Use Google-style docstrings: + ```python + def my_function(param1: str, param2: int) -> bool: + """Brief description of the function. + + Args: + param1: Description of param1 + param2: Description of param2 + + Returns: + Description of return value + + Raises: + ValueError: When something goes wrong + """ + ``` +4. **Async/Await** - Use async/await for I/O operations +5. **Error Handling** - Use appropriate exception types and provide clear error messages + +## πŸ§ͺ Testing Guidelines + +### Writing Tests + +1. **Test Coverage** - Aim for high test coverage, especially for new features +2. **Test Organization**: + - Unit tests in `tests/unit-tests/` + - Integration tests in `tests/integration-tests/` + - Mark integration tests with `@pytest.mark.integration` + +3. **Test Naming**: + ```python + def test_function_name_with_condition_returns_expected(): + """Test that function_name returns expected when condition is met.""" + ``` + +4. **Async Tests**: + ```python + import pytest + + @pytest.mark.asyncio + async def test_async_function(): + result = await my_async_function() + assert result == expected + ``` + +5. **Fixtures** - Use pytest fixtures for common setup: + ```python + @pytest.fixture + def sample_agent(): + return AgentBuilder().with_name('test').build() + ``` + +### Running Tests + +```bash +# Run all unit tests +pytest tests/unit-tests/ + +# Run specific test file +pytest tests/unit-tests/test_agent_builder.py + +# Run with verbose output +pytest -v + +# Run with coverage +pytest --cov=flo_ai --cov-report=term-missing + +# Run only integration tests (requires API keys) +pytest tests/integration-tests/ -m integration + +# Skip integration tests +pytest -m "not integration" +``` + +### Test Requirements + +- All tests must pass before submitting a PR +- New features should include tests +- Bug fixes should include regression tests +- Integration tests are optional but encouraged for LLM integrations + +--- + +## πŸ“š Documentation Guidelines + +### Code Documentation + +- **Docstrings** - All public functions, classes, and methods should have docstrings +- **Type hints** - Use type hints for better IDE support and documentation +- **Comments** - Add comments for complex logic, but prefer self-documenting code + +### Documentation Updates + +When adding new features, update: + +1. **README.md** - If the feature is user-facing +2. **API Documentation** - If adding new APIs +3. **Examples** - Add examples in `flo_ai/examples/` if applicable +4. **Docstrings** - Update docstrings for any changed functions + +### Documentation Format + +- Use Markdown for documentation files +- Use MDX for the documentation site +- Include code examples where helpful +- Keep documentation up-to-date with code changes + +--- + +## πŸ“ Commit Message Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +(): + + + +